Localize a web app
Connect translated catalogs to your framework's locale selection, resource loading, and rendering checks.
If your web app already renders messages from locale files, keep that working arrangement. Lingo.dev can translate the source catalogs while the existing library continues to choose a locale, load messages, and render them. Complete that cycle for one screen before translating the rest of the application.
This guide covers existing keyed catalogs across frameworks. For source-and-context messages with @lingo.dev/react, use the React quickstart or migration guide. Its extracted identities differ from the keys in an existing i18next or next-intl catalog.
Establish one end-to-end fixture #
Choose a screen with a label, a variable-bearing message, and a plural or conditional message. Render it in the source language through the existing library. Keep its namespaces, interpolation syntax, and lookup keys; a generic JSON translation does not convert one library's message grammar into another's.
For an existing react-i18next source at public/locales/en/translation.json, initialize the CLI from the project root:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo linkThe linked .lingo/config.json should have this shape:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [{ "pattern": "public/locales/en/translation.json" }]
}Keep the actual organization and localization engine IDs produced by linking. For another framework, substitute its source path from the sections below. Select only source catalogs, and make the target path match the loader. Use explicit target paths for layouts without a locale segment.
Translate missing targets with:
lingo push --backfill-missing --waitAfter completion, inspect the generated catalog and load the screen in Spanish. Compare the same variable values and plural cases in both languages. The framework-specific step below connects that file to the actual request or build. A first plain push can save a baseline without requesting missing translations.
Keep targets unchanged while waiting writeback runs. If existing local corrections need conflict protection, submit without --wait, inspect lingo pull --dry-run, then retrieve in the submitting checkout. See Preserve reviewed translations.
React with react-i18next #
With react-i18next, keep your existing namespaces and lookup calls. A source at public/locales/en/translation.json maps to public/locales/es/translation.json. If the application uses several namespaces, configure each English source rather than a glob that also captures the generated Spanish files.
Make the i18next resource loader request the target locale and namespace. Then use the existing useTranslation calls to render the fixture. Check variable substitution and the plural-key convention used by your installed i18next version. A generic JSON translator does not convert one library's plural schema into another's. In a client application, inspect the resource network request as well as the visible text; English fallback can conceal a missing Spanish file.
Next.js App Router with next-intl #
For next-intl, a common source is messages/en.json, producing messages/es.json. Configure request-time locale resolution and load the matching messages in your next-intl setup. Keep locale-aware routes and navigation consistent with that choice.
Render the fixture through both a direct target-locale request and navigation from another locale. Check server-rendered content, client hydration, and ICU variables or plurals. Translation of the message file alone does not add an App Router locale segment or a language switcher. For long-form documents alongside these UI catalogs, use Markdoc with Next.js.
Next.js Pages Router with next-i18next #
With next-i18next, configure the source pattern to match your existing locale directory and namespaces. If those are public/locales/en/common.json and public/locales/en/checkout.json, translate both to their Spanish siblings. If you use messages/en.json, retain the custom loader that actually consumes it.
Load the required namespaces through the page's existing server-side or static data-loading path. Verify a direct localized page request and a client-side route change. Check that the initial page data and client runtime agree on locale and namespace; a translated file on disk is insufficient if the page never includes it.
Vue with vue-i18n #
vue-i18n can load dictionaries such as src/locales/en.json and src/locales/es.json. Translate the English source and register or dynamically load the Spanish dictionary in the existing i18n instance. Set the selected locale where your app already manages it.
Exercise $t or useI18n calls on the fixture. Check nested keys, interpolation, and the installed library's plural message syntax. Test a locale switch without reloading as well as a fresh page load. If dictionaries are bundled through imports, confirm the translated file is included in the build.
Nuxt with the i18n module #
For Nuxt i18n, translate a source such as locales/en.json into locales/es.json. Register the locale and file in the module configuration appropriate to your installed version. Align the configured language directory with the CLI's output path.
Follow the project's locale-aware route strategy rather than creating a second strategy in the translation job. Verify server rendering, lazy loading, localized navigation, and metadata on the fixture page. Adding a target to the translation configuration does not itself add that target to Nuxt's locale list.
Svelte and SvelteKit dictionaries #
For svelte-i18n, translate a dictionary such as src/lib/locales/en.json. Register the target dictionary or its lazy loader and initialize the selected locale before the component needs it.
Render the fixture through the application's existing translation store. Test a fresh server-rendered request if the app uses SSR, then a client locale change. Check that locale state is isolated between server requests and that the target dictionary finishes loading. Avoid using fallback output as proof of completed translation.
Angular XLIFF #
Use Angular's i18n workflow to mark and extract messages first. The XLIFF handler supports XLIFF 1.2 and 2.x, including plain text and inline codes. Text inside paired codes such as <g> and <pc> is translated while their structure is retained; standalone codes such as <ph> remain protected. Keep message and inline-code identifiers stable, and inspect the returned placeholders before importing the target catalog.
For supported input, src/locale/en/messages.xlf maps to src/locale/es/messages.xlf. XLIFF does not use suffix substitution from messages.en.xlf to messages.es.xlf; use the locale directory or an explicit target template. Preserve message identities when returning translations to Angular.
Register the target file in Angular's localization build configuration, build the target-locale bundle, and serve it to inspect the screen. Angular's compile-time localization differs from a runtime JSON loader: changing the browser locale does not build a missing localized bundle. Check message coverage and placeholder rendering before accepting the bundle.
Astro #
For UI labels, translate src/i18n/en.json into its target sibling and make your own dictionary loader select it. For content collections, translate the locale-specific Markdown or MDX sources and use the static-content workflow.
Configure Astro's locale routing independently of translation. Build and visit the generated target routes, checking links between locale versions and any client islands that load their own messages. A content collection and an island's UI dictionary may need separate inputs.
Laravel #
For Laravel localization, a PHP source such as lang/en/messages.php maps to lang/es/messages.php. Preserve array keys and runtime replacement names. Use the PHP format reference before selecting files containing executable code beyond the supported catalog structure.
Set the request locale through the application's existing middleware or controller policy and render messages through Laravel's translation helpers. Exercise replacement values and plural selection. Test a request in each supported locale and a fallback case; translated files do not choose the locale for the request.
Django #
Use Django's extraction workflow to create locale/en/LC_MESSAGES/django.po, then translate that source PO into the target locale directory. Preserve gettext message identities, context, and interpolation. Compile the translated PO into the resource Django actually loads using the project's existing gettext build step.
Configure Django's language selection and language list. Verify a localized request through the translation middleware and render singular and plural calls. A PO file existing on disk does not prove its compiled catalog is current. See Gettext for the file contract.
Rails #
Rails identifies locale-root YAML by the root key. Select yaml-root-key, then verify Rails' locale configuration, helpers, and interpolation. Localize a Rails app owns the complete procedure, including per-concern files, request locale switching, and scoped updates.
Make recurring translation produce reviewable output #
Once the screen works, add the remaining source catalogs and their loaders. Keep accepted targets with the source revision and CLI lockfile. Later source changes use lingo push --wait for the ordinary delta; a positional file pattern selects scoped planning instead.
Choose source-change triggers and writeback through the GitHub App or CI recipes. GitLab, Bitbucket, and GitHub Actions recipes run the CLI and need their own repository writeback. Run the framework's build or resource checks on the output, then review the translated meaning. lingo check does not validate every framework or establish PHP, PO, or XLIFF completeness.
An agent can help inspect loaders and propose configuration changes. Apply the same source-selection, build, and rendered-screen checks to those edits before expanding the workflow.