Store Localization

One design, up to 57 languages

The end state: one project, one layout, several store languages, rendered into a screenshots/<locale>/ folder per language under osg/out/ that fastlane's deliver can upload as is, with osg verify exiting 0 for every locale.

The model, which is the thing everyone gets wrong

A language is an overlay, not a copy. The project keeps one set of artboards and one layout. Only these can differ per language:

• the text content
• the screenshot inside a device frame
• the font, the font size, the line height, the box, the position of an individual element
• whether an element is shown at all

Everything else is shared. There is no per language artboard, no duplicated project, and no second design to keep in sync. That is the whole point: a layout fix lands in every language at once.

Two consequences that will otherwise cost you an hour:

1. Every editing tool writes the base document, the one all languages share. update_element changes the copy every language starts from. Only set_localized_text, set_localized_texts and set_locale_override write one language.
2. Rendering follows the canvas. To export a language you switch to it and then export. osg render does that per locale for you; if you are driving tools by hand, set_locale then export_all.

Step 1: name the base language before anything else

The base language is the language the design is written in. It labels the source that every translation is tracked against, and it names the base folder in both store uploads.

It is locked the moment the project has any export language, because every override is hashed against a base string and re-basing would silently re-point all of them. So set it first.

[{ "tool": "add_locales", "args": { "locales": ["de-DE"], "baseLocale": "en-US" } }]

baseLocale is accepted only on that first call. After that, set_base_locale refuses.

Step 2: add the store locales

Codes are store locales, not two letter languages: en-US and en-GB are different listings, and so are zh-Hans and zh-Hant. pt alone is ambiguous and is refused.

npx -y open-screenshot-generator@0 edit --script osg/locales.json

[
  { "tool": "list_supported_locales", "args": { "query": "chinese" } },
  { "tool": "add_locales", "args": { "locales": ["de-DE", "ja", "pt-BR", "zh-Hans"], "autoFont": true, "autoFit": true } },
  { "tool": "list_locales", "args": {} }
]

list_supported_locales is the catalog of all 57, with the code to add by, whether a machine engine can draft it, what App Store Connect and Google Play each call it, and which font has to be substituted for its script. Call it before add_locales rather than guessing a code.

• autoFont (default true) substitutes a family that can actually draw the script. Turn it off only if you have checked the design font covers Japanese, Arabic or Thai. It does not.
• autoFit (default true) shrinks a translation that overruns its box instead of clipping it.
• machineTranslate (default false) drafts every new language with the engine right away. Leave it off, see the next step.

Mirror the same list into locales in osg/osg.config.ts so a fresh clone renders the same set.

Two vocabularies, and they resolve against different lists. add_locales and set_base_locale resolve against the catalog, because a language being added is by definition not in the project yet. Every other language tool resolves against the project's own list. Using the wrong one either invents a locale with no override map or refuses a language that does exist.

Step 3: write the copy, because you are the better translator

Store copy is exactly what a machine translator is worst at: it is short, idiomatic, brand specific and load bearing. An agent that reads the app writes better German headlines than the engine does. So the preferred path is read, translate, write back, in two calls.

[{ "tool": "list_translations", "args": { "filter": "untranslated", "limit": 200 } }]

Each cell says where its string came from, which is what tells you what you may overwrite:

Then write them all in one call. One round trip, one undo step, one save:

[
  { "tool": "set_localized_texts", "args": { "writes": [
    { "elementId": "headline", "locale": "de-DE", "text": "Schlaf endlich durch" },
    { "elementId": "sub", "locale": "de-DE", "text": "Jede Nacht, automatisch" },
    { "elementId": "headline", "locale": "ja", "text": "ぐっすり眠れる夜へ" }
  ] } }
]

An empty string, or a string identical to the base copy, clears the translation and the element falls back to the base. Everything written this way is marked as human written, so a later engine run will not overwrite it.

Translation notes that are not optional:

• Translate the benefit, not the words. A literal German headline is usually 40 percent longer and says less.
• Keep product names, feature names and units in the source language unless the app itself localizes them.
• German, Finnish and Russian run long. Dutch and French run long. Japanese, Korean and Chinese run short and want a larger size, not a smaller one.
• Arabic, Hebrew, Farsi and Urdu align to the correct edge automatically. The composition is not mirrored: nothing flips element positions across the board. If a right to left layout needs the badge on the other side, that is a per locale position override, Step 5.

The machine engine is the fallback, for a language you do not read and for refreshing its own earlier drafts:

[{ "tool": "translate_locales", "args": { "locales": ["th"], "only": "empty", "guidance": "informal, second person, keep product names in English" } }]

only: "stale" refreshes drafts whose base copy has since changed. Strings a person wrote are skipped unless includeManual is set, and leaving it off is what protects reviewed copy. If no engine is configured, the tool says so and tells you to write the strings yourself, which was the better path anyway.

Step 4: the CSV round trip, for a human translation agency

[{ "tool": "export_translations_csv", "args": {} }]

The result is a JSON document, not a file: { csv, locales, rows }, where csv is RFC 4180 text with one row per string, the ids first, then the base language, then a column per language. Write the csv field to a file yourself and send that file. It is the format an agency takes.

npx -y open-screenshot-generator@0 call export_translations_csv | jq -r .csv > osg/translations.csv

(npx -y open-screenshot-generator@0 call export_translations_csv | ConvertFrom-Json).csv |
  Set-Content -Encoding utf8 osg/translations.csv

When it comes back, read the file and send its contents as the csv argument. Build the call programmatically rather than pasting a spreadsheet into a prompt:

[
  { "tool": "import_translations_csv", "args": { "csv": "<the file contents>", "dryRun": true } },
  { "tool": "import_translations_csv", "args": { "csv": "<the file contents>" } }
]

• Rows match on artboardId plus elementId, falling back to the base string when the ids do not line up and exactly one element has that string. So do not let the agency reorder or renumber.
• An empty cell means "I did not translate this one" and never clears an existing translation. That is deliberate: a sheet that came back with three columns filled will not wipe the fourth.
• Only languages the project already has are written. Run add_locales first.
• Always run dryRun first and report what it says it will change.