mirror of https://github.com/LorenEteval/Furious.git synced 2026-09-22 23:08:08 +03:00

Files

T

Signed-off-by: Loren Eteval <loren.eteval@proton.me>

2026-09-08 15:52:24 +08:00

Translation catalog guidance

Inherit the root and package guides. This scope preserves the split between extracted catalog structure and human-reviewed translations.

Source and generation contract

Furious/Externals/GenTranslation.py is generator-managed, but its language values and isReviewed flags are curated data. Repository-root Translation.py owns source extraction and catalog structure; neither file is disposable.
Run python Translation.py --target <language> with the repository interpreter for an intentional extraction/update. It rebuilds source membership, drops stale keys, preserves reviewed target text, and reports collisions. Automatic translation is currently disabled: unresolved/unreviewed target values may be replaced with the source text. Review the diff before treating the command as a harmless refresh, especially with --ignore.
Existing dictionary order is generally preserved; the generator does not enforce a universal field order and source traversal can affect newly discovered entries. Keep diffs stable without claiming canonical sorting. source contains deduplicated fully qualified modules and is rebuilt by extraction rather than manually curated.
Inspect the full diff. Preserve deliberate translations/review flags, HTML/newline semantics, and natural RU/ZH meaning; mark an entry reviewed only after a human has verified it. Do not hand-maintain the generated source module list.

_() normally receives one static literal. The only supported dynamic form is an f-string composed solely of bare names imported from Furious.Frozenlib.Constants; ordinary placeholders, attributes, calls, conversions, format specifications, concatenation helpers, and .format() are not extractable.
Keep runtime interpolation outside the translatable expression. Translate UI language, not identifiers, protocol values, user-defined names, persisted values, paths, or diagnostic payloads.
When a control stores source text for later retranslation, update that source instead of manually translating one rendered instance. State-driven controls may deliberately reapply semantic state rather than call a generic base retranslator; preserve user-defined values in either path.

Run extraction for every affected language, inspect collision/unreviewed diagnostics and the complete catalog diff, then run it again to check stability. Collision and write failures are logged rather than guaranteed to produce a nonzero process exit; exit status alone is not validation. Exercise runtime lookup and UI retranslation under explicit locales; tests/test_models_and_services.py and tests/test_ui_behavior.py cover extraction/UI consumers.
Translation generation is a scoped repository mutation: do not run it as an incidental formatter, and do not accept broad catalog churn without tracing each changed source literal or intentional stale-key removal. Update this guide when extraction or review semantics change; do not generalize generator-managed membership into a ban on curated text.