Skip to content
Locize
LoginRegister

What happens when I change the source (reference) language?

The source language is the language your team translates from. The API, the CLI and the i18next backend call it the reference language (referenceLanguage, referenceLng); it is the same setting. You choose it when you create the project and you can change it later in the project settings under Languages with Change source language. The change applies to all versions of the project.

Short answer: it is a settings change. No translation is modified, moved or deleted, and you can switch back at any time. (Changing a language's code, e.g. nn to nb-NO, is a different operation: see How to rename a language?) A few things are measured against the new source language from then on, and, depending on how you integrated Locize, one or two settings on your side should follow.

What does not change

  • Your content. The previous source language keeps all its values and simply becomes a regular target language; the new source language keeps its values and becomes the source. Namespaces, versions, API keys, users, tags and the history stay as they are.
  • What your app loads. The published files on the CDN stay the same and are served from the same URLs. Only the languages metadata (/languages/{projectId}, the languages.json your integration may read) flips its isReferenceLanguage flag once the change has been processed. Anything that only reads translations (i18next-locize-backend loading, downloads, the GitHub action in download mode) is unaffected.
  • Reversibility. Change it back the same way, nothing is lost in between.

What changes inside Locize

  • Progress and statistics. The new source language counts as 100 % by definition. Every other language, including the previous source language, is measured against the keys of the new source language. The numbers are recalculated in the background right after the change, so give the progress bars a moment.
  • Keys the new source language does not have. A key that exists in the previous source language but has no value in the new one no longer counts as "to be translated" for the other languages, and the editor flags it with issue 301, "is not found in the source language". Best practice: make the new source language complete (100 % translated) before you switch. Then both key sets are identical and nothing gets flagged. The dialog warns you when the language you pick is not fully translated.
  • Machine translation and translation memory suggestions in the editor use the new source language as their source. (In the bulk translate panels you can still pick another source language explicitly.)
  • Automatic Translation is triggered by keys created in the source language and translates from it. Keys added in the previous source language do not trigger it any more.
  • Checks and issues compare each target language against the new source language: placeholders and plural forms, glossary terms, max characters, and "the source changed after translating" (issue 302).
  • Language-scoped permissions. Users whose permission is scoped to specific languages can always read the source language (they need it as the source column). Adding and removing keys requires the source language in the scope, see user management, so a scope that included the previous source language but not the new one becomes translate-only.
  • Translation orders you place with a translation service take the source language as the source of the order.
  • A referenceLanguageChanged event is sent to your webhooks and shown in the project notifications.

What to check in your integration

  • i18next fallbackLng. If you set it explicitly, nothing changes unless you want it to. If you let i18next-locize-backend provide the options (getOptions()), fallbackLng follows the source language of the project and switches automatically, so untranslated keys fall back to the new source language at runtime.
  • saveMissing with i18next-locize-backend. Missing keys are only sent while the app runs in the backend's referenceLng (the option, which falls back to your fallbackLng). Point referenceLng / fallbackLng to the new source language, and make sure the default values in your code (t('key', 'default text')) are written in that language from then on: they become the source text.
  • locize CLI (sync, save-missing, migrate). The CLI reads the reference language from the project. After the change, locize sync treats the local files of the new source language as the source of truth: it adds and removes keys based on them and, by default (--reference-language-only), only reads those files. If your repository or CI currently maintains the previous source language as the source files, adapt that first.
  • GitHub actions (locize/sync, locize/translate) run the same sync flow, so the same applies to your CI.
  • MCP server. find_missing_translations compares against the reference language and report_missing_keys adds new keys to it, so both follow the change automatically.

Suggested order

  1. Complete the new source language (translate what is still missing there).
  2. Change the source language in the project settings.
  3. Adapt fallbackLng / referenceLng, the CLI or CI setup, and the default values in your code.
  4. Once the statistics are recalculated, check the progress bars and the issues filter of the editor.