05 / 15 · Languages & translations

Languages and translations

Forma includes two configurable languages, supplied as complete English and Greek examples. Each has a static page and translated marketing text, metadata, interface labels, pricing labels, media captions, testimonials, newsletter copy, dialogs and preference inventory. Buyers choose the pair and provide their own translations; there is no automatic translation service or content editor.

The normal setup uses one language settings file and two stable content files. You do not need to rename content files, edit imports or create route components for another pair.

The three-step setup

  1. Choose your two languages in src/config/languages.ts: codes, native names, reading direction, formatting locale and default code.
  2. Edit the text values in src/content/primary.ts and src/content/secondary.ts. Keep the supplied export names, object keys and required placeholders.
  3. Run npm run format and npm run check, then preview both language URLs with npm run start after stopping development.

Before first setup, follow Start here for extraction, Node/npm and npm ci. Run all commands from source/, beside package.json.

Configure the language pair

The supplied languageSettings object is:

export const languageSettings = {
  defaultCode: 'en',
  primary: {
    code: 'en',
    nativeLabel: 'English',
    direction: 'ltr',
    formatLocale: 'en-US',
  },
  secondary: {
    code: 'el',
    nativeLabel: 'Ελληνικά',
    direction: 'ltr',
    formatLocale: 'el-GR',
  },
} satisfies LanguageSettings;

Edit this object inside the existing file; keep its type declarations and helper functions. primary always uses primary.ts, and secondary always uses secondary.ts, even when their codes change.

FieldMeaning
codeLanguage tag used in the URL, HTML language and language alternates, for example en, de or pt-BR. Use two distinct valid tags.
nativeLabelName shown in the switcher, written for readers of that language, such as Deutsch.
directionltr for left-to-right or rtl for right-to-left. Check the actual translated layout and font.
formatLocaleLocale for price/number formatting, such as de-DE. This changes formatting, not translations or currency.
defaultCodeExactly one of your two configured codes. Used for the root entry and default missing-page content.

The system deliberately supports exactly two slots. Adding a third language requires source changes and tests; adding a third property is not a documented configuration workflow. Codes cannot contain slashes or arbitrary URL text. Invalid or duplicate tags, empty names, an unsupported direction or an unconfigured default produce a configuration error.

The compact header trigger displays the uppercase base part of the selected code: pt-BR and pt-PT both display PT. Its accessible name includes that visible abbreviation, the nativeLabel and the translated language-control label; the open menu uses nativeLabel. For a regional pair, choose clear, distinct names such as Português do Brasil and Português de Portugal so visitors can tell the choices apart. Different compact abbreviations would require a deliberate control customization; changing a code does not provide a separate abbreviation setting.

Complete English and German example

This worked example replaces the supplied Greek slot with German while keeping English as default. Keep an untouched copy of the original files first.

  1. In src/config/languages.ts, replace the existing languageSettings object with the following values. Keep everything else in the file:
export const languageSettings = {
  defaultCode: 'en',
  primary: {
    code: 'en',
    nativeLabel: 'English',
    direction: 'ltr',
    formatLocale: 'en-US',
  },
  secondary: {
    code: 'de',
    nativeLabel: 'Deutsch',
    direction: 'ltr',
    formatLocale: 'de-DE',
  },
} satisfies LanguageSettings;
  1. Open the supplied complete German content example in a plain-text editor. Select its entire contents, copy them, then replace all contents of src/content/secondary.ts and save. This is a complete file replacement, including the existing secondaryContent export and type import. Keep the filename secondary.ts. Leave primary.ts as the English example.
  2. Run:
npm run format
npm run check
npm run start

Stop an existing dev/preview process before the last command. On Windows use npm.cmd if PowerShell blocks the npm script wrapper.

Expected result: /en/ shows English and /de/ shows German, the switcher offers English/Deutsch, and /de/ has German titles, dialogs, FAQ and cookie copy. Price formatting uses de-DE while the shared currency and numeric prices stay unchanged. The old /el/ route is no longer generated and should be a missing page. The root / uses the configured default, except for an allowed saved language described below.

The German file is a translation of Forma's fictional example product, not ready-to-publish claims about your business. Replace its example statements and obtain an appropriate language review before launch. To undo the example, restore the original two files and rebuild.

To make German the default, change only defaultCode to 'de' after the pair is configured. Keep the slots and exports unchanged. Preview a root visit with no saved preferences to confirm the new default.

Edit all translated text

Both content files share the same structure. Translate values, not property names. Each includes metadata, navigation names, hero, benefits, general cards, workflow/gallery captions, testimonials, pricing labels/features, FAQ, footer, appearance options, newsletter and demo-access dialog wording, missing-page messages, cookie inventory and language switcher labels. The dialog object includes the local name/email labels, validation, demo explanation, confirmation and access-link text; translate all of them. When an enabled newsletter uses popup placement, its headings and close-control label use newsletter.eyebrow, title, description and closeLabel instead. The provider's own Form labels/messages are configured in your Kit language slots separately.

Form notices, errors and response states are required translations too. Keep dialog.nameError, dialog.emailError, dialog.kitFormNote and dialog.kitSuccessDescription; newsletter includes emailError, consentError, nativeNotice, submitPendingLabel, requestReceivedMessage, requestUnknownMessage, submissionErrorMessage and guardTitle. Translate the full object, not just this list. Native Kit responses must distinguish a request received from confirmed subscription; demo-access copy must keep marketing optional and avoid authentication claims. The complete German replacement file includes these required fields.

Shared brand, colors, prices, media URLs, testimonial identities, CTA destinations and newsletter settings stay in src/config/site.ts. You do not repeat them in each translation. See Customization for their exact locations and recipes.

Keep matching array counts/order in both dictionaries and their shared settings. Feature cards, workflow panels, product images, testimonials and pricing plans use configurable arrays. Adding an entry means adding its translated counterpart to both dictionaries; a shared image also needs meaningful translated alternative text. The three-to-six workflow recipe is in Customization. Add matching FAQ items in both languages too.

Kit-backed modes use stable primary and secondary public Form settings. With kit-native newsletter or demoAccess.mode: 'kit', visible fields and status text come from Forma's dictionaries; provider verification, validation responses and confirmation email remain Kit-owned. With newsletter kit, the embedded Form's fields, consent and messages must be translated in Kit itself. Reusing one English Form does not translate it. Configure separate Forms for demo and newsletter when both are active. Shared video/caption assets are not automatically translated either; see Email signup and Kit.

The supplied product clip is silent; its descriptive public/product/demo.vtt track is English on both pages. Review or replace that shared track for your chosen audience. Translate all player labels in each dictionary's preview object, including videoControlsLabel, videoSeekLabel, videoMuteLabel, videoUnmuteLabel, videoVolumeLabel, videoCaptionsLabel, videoFullscreenLabel and videoExitFullscreenLabel, alongside the existing playback/error labels. These labels translate the surrounding controls; they do not translate media. See Product screenshots and video.

Preserve placeholders

Placeholders are filled by the template. Translate the surrounding text without translating the words inside braces.

TokenUsed for
{name}Shared product name.
{total}, {seat}Yearly plan billing line; both are required in sections.pricing.annualBillingLabel.
{proAnnual}, {businessAnnual}Formatted annual totals of the second and third example plans.
{days}Duration in the necessary and language cookie inventory; required in both duration fields.
{language}Destination language name in languageSwitcher.switchTo; required in this field.
{index}, {total}Product image position in preview.imageLabel; both are required in this field.

For example, Switch to {language} may become Zu {language} wechseln. Keep the braces and token exactly. Required technical tokens must occur exactly once and only in their documented fields: {total}/{seat} in the annual billing line, {days} in each cookie-duration line, {language} in the switcher destination label and {index}/{total} in the product image-position label. Do not invent tokens. npm run check reports the language and field path for missing/empty fields, mismatched arrays or broken placeholders. It checks structure, not translation quality or truth.

URLs, switching and remembered choices

The default pair generates /en/ and /el/. Each is a real static page with its translated HTML. A direct language URL always takes priority over a saved preference. No browser-language guessing is used.

The root / contains the configured default language. When NEXT_PUBLIC_SITE_URL is set before building, its canonical metadata points to that language URL. With valid optional permission and an available saved language cookie, the root may redirect before paint to the remembered language page. Without permission or with blocked access, the root uses the default. Explicit language URLs remain usable without JavaScript; the optional remembered root redirect needs JavaScript. The shared missing-page fallback uses the configured default language, including an unknown language URL.

Switching navigates to the other language page and preserves the current section fragment. It loads that page's initial interface state; the selected preview image, testimonial position, billing toggle, information/signup dialog and provider Form state are not a persistent application. Do not promise that every transient interaction survives a language change.

Language switching works when preference storage is declined. With valid permission, Forma remembers the selected language in a host-only cookie. Withdrawal attempts to remove that cookie and the saved theme. The language URL you are currently viewing still determines its language. Cookie/storage restrictions may prevent saving or physical cleanup. See Cookies and preferences.

Right-to-left languages and fonts

For a language written right-to-left, set direction: 'rtl' and supply matching text. Forma sets the document direction and includes directional layout rules. Review navigation, cards, media captions, testimonial controls, form fields, buttons, numbers, focus and mixed-script text at phone and desktop widths. Check the provider's embedded Form too. A setting alone cannot verify an unfamiliar translation or every future customization.

The bundled Manrope font is a Latin subset. Greek uses available system fallbacks; their appearance varies by device. For Arabic, Hebrew or another writing system, check glyph coverage and consider an appropriately licensed local font with the required characters. When replacing the file, update or remove the existing unicode-range declaration in src/components/document-frame.tsx if its coverage differs; changing only the file path can leave new characters excluded by the old range. The template does not ship a font covering every language. Keep font notices and verify file size/layout after replacement. See Appearance.

Language SEO and static hosting

Each language page has its translated title/description and matching HTML language/direction. Setting NEXT_PUBLIC_SITE_URL to your real public HTTPS origin before building also adds the canonical language URL and alternate links to both configured languages; local builds without that setting omit those links. The build generates a sitemap for the configured language pages, using the public origin when set and the local preview origin otherwise. See SEO for metadata and final checks.

Upload the complete out/ contents, including both language directories. Your static host must serve directory index.html files. No Node application server, database, translation service or new proxy is needed. Retest direct visits and refreshes of both language URLs on the actual host; see Deployment.

If changing codes on an already published site, the old URLs are removed from the new build. Plan any old-to-new URL redirects in your host's established configuration; Forma does not create host-level redirects automatically. Deploy a complete clean export so an old language directory is not accidentally left public.

Check your pair before launch

  • Open both direct language URLs and confirm the correct text, switcher selection, HTML language and direction.
  • Switch both ways with and without preference permission; test the section fragment and fresh demonstration state.
  • Verify both metadata titles/descriptions and configured canonical/alternate/sitemap URLs.
  • Review pricing, free-form numbers, placeholders and every conversion destination in each language.
  • Test cookie banner/inventory, appearance menu, product images/video, testimonials, newsletter in its configured section/popup, demo-access form and confirmation, FAQ, keyboard operation, narrow layouts and fonts.
  • Test a root visit with no saved preference, an allowed remembered language, withdrawal, a stale language code and blocked browser storage.
  • Build and inspect production after edits. Source changes do not refresh the old static export.

If a check fails, use Troubleshooting. Include the language code and first field-path error when asking for Support; translation services and new language-specific integrations are separate work.