Add a language without retranslating everything
Introduce a new target locale, preserve accepted translations, and verify that the application can use the new resources.
Adding a language connects three pieces of work: selecting it for translation, creating the resources, and making the application load them. A new language option in the interface does not create its catalog. A translated catalog does not make the route use it.
Start with recoverable source and accepted targets. Record the intended locale, including region or script where needed. pt-BR and pt-PT name different audiences whose wording requirements may differ.
Inspect the existing layout and guidance #
List source patterns, current targets, and expected output paths. Separate target files can be added independently; a shared Xcode String Catalog stores several locale slots in one file, so file existence alone cannot establish coverage.
Review model coverage, terminology, register, and voice for the new audience. Reuse neighboring-locale guidance only where it applies. A term can remain shared while address conventions differ. Right-to-left language support also needs application direction and layout work, not only translated strings.
Add the target to the current CLI project #
Current CLI targets come from targetLocales in .lingo/config.json. push has no --target-locale or --locale option. In a monorepo, confirm the project configuration selected by the working directory.
Before adding the target, finish any pending ordinary source updates for the existing languages with lingo push --wait. Complete review, retrieve the output, and inspect those targets against the current source. Keep that source revision fixed while adding the new language.
Backfill leaves existing target files unchanged. When it creates only the new language's files, it retains an existing source baseline so a later ordinary push can still process pending edits for the other languages. Completing those updates first keeps the existing and new targets aligned with the same reviewed source revision.
Then add the target to the installed, authenticated, linked project's configuration and inspect planned missing-file work:
lingo push --backfill-missing --estimate
lingo push --backfill-missing --waitThe estimate translates nothing and creates no job, but it uploads files the server lacks for planning. It is not offline and is not a guaranteed price. Backfill visits configured patterns and fills missing target files; it does not fill new keys inside an existing target. After the new locale is current, later ordinary source changes use lingo push --wait against the saved baseline.
Shared XCStrings catalogs plan per locale inside one file; inspect the new entries using the iOS workflow.
If the request must target only one locale, narrow targetLocales in a controlled branch or job configuration and restore the full list afterward. Do not add force merely to reach the new language: it retranslates existing targets in scope and can replace reviewed wording. Push documents those distinctions; the CLI v0 locale reference covers that older generation's flags.
Give an assistant the same boundaries #
An agent can inspect layout, propose locale guidance, and prepare the configuration diff. Specify whether it may change local files, organization-owned localization-engine settings, or both. Delegation distinguishes those authorities.
Ask it to explain applicable primary/fallback models and shared versus locale-specific guidance. Confirm saved state before comparing output. Locale resolution explains selection; a model preference is not a language-quality benchmark.
Verify the new audience's result #
Compare returned paths and the diff with the intended scope. Existing accepted targets should remain unchanged unless a source update or authorized correction explains the change. Validate variables, plural branches, and locale metadata with the application's resource tooling.
Load representative content in the new locale. Check fallback, overflow, and direction as well as meaning. Keep the source revision and result for measurement before expanding coverage.
Removing a locale from configuration stops selecting it for new work; it does not delete resources or runtime routes. Decide those changes separately, especially when one shared catalog contains source and several languages.