localization

name	localization
description	Use when updating KMReader translations in Localizable.xcstrings after code changes. Covers build/localize refresh, missing key discovery, context lookup, and deterministic updates through misc/translate.py.

KMReader Localization

Maintain and complete KMReader translations in KMReader/Localizable.xcstrings.

When To Use

• The user asks to fill missing translations.
• New localized strings were introduced and need all supported languages.
• The user mentions misc/translate.py, make localize, or missing localization entries.

Standard Workflow

Hard requirement:

• make localize must be preceded by a full make build for the current code state.
• Without that build, extracted localized strings data may be stale, and Localizable.xcstrings will not be updated correctly.

Default order:

1. Run a full make build once to refresh extracted strings data.
2. Sync extracted strings data into Localizable.xcstrings.
3. Fill missing translations.

Only skip the build step when it is already confirmed that the current code changes have been through a full make build. If that is not explicitly confirmed, run make build before make localize.

make build
make localize

Missing Translation Check

./misc/translate.py list

• This lists keys with missing languages.
• If output is No missing translations found., no translation update is needed.

Per-Key Process

1. Understand key meaning and UI context.
2. Locate usage in code when needed to avoid semantic drift.
3. Prepare all target languages first, then write once.

rg -n "String\\(localized: \"<KEY>\"\\)|\"<KEY>\"" KMReader Shared KMReaderWidgets

Optional terminology alignment source (if present):

• ../komga/komga-webui/src/locales/

Current supported target languages:

• de, en, es, fr, it, ja, ko, ru, zh-Hans, zh-Hant

Deterministic Update Command

Always write all target languages in one command to avoid partial updates. Run ./misc/translate.py update commands sequentially. Do not run multiple update commands in parallel against the same KMReader/Localizable.xcstrings file, because each invocation rewrites the file and concurrent writes can corrupt the JSON. Parallelism is only safe for read-only steps such as rg or ./misc/translate.py list.

./misc/translate.py update "<KEY>" \
  --de "<German>" \
  --en "<English>" \
  --es "<Spanish>" \
  --fr "<French>" \
  --it "<Italian>" \
  --ja "<Japanese>" \
  --ko "<Korean>" \
  --ru "<Russian>" \
  --zh-hans "<Simplified Chinese>" \
  --zh-hant "<Traditional Chinese>"

If Localizable.xcstrings becomes invalid JSON at any point, restore it to a known-good state first, rerun make localize, and then repeat the missing-key updates sequentially.

Quality Rules

• Preserve placeholders and format markers exactly: %@, %d, %lld, %f, %1$@, \\n.
• Keep tone consistent with product domains (Reader, Series, Read List, Offline Sync).
• Do not modify entries where shouldTranslate == false.
• Do not rewrite unrelated keys; only update requested or missing ones.

Final Verification

./misc/translate.py list

If missing items remain, continue until the list is empty.