Add mod documentation in seven languages
This commit is contained in:
cthangover committed
1 parent
21c38f7e9a
commit
33b9755d4c
15 files changed
+497
-8
No files matched your search
+69
@@ -0,0 +1,69 @@
|
||||
# Locale Atlas — every translation key of every mod
|
||||
|
||||
The Locale Atlas maps the localization of all installed mods: which keys each mod declares in each language, where the keys are used — scenarios, C# code, JSON data, collections, scenes, manifests — and what is wrong. It separates two kinds of problems:
|
||||
|
||||
- **errors** — broken text: a key that is used but declared nowhere, an empty value, one key with two different values in one mod, a file the loader will not read, a broken encoding;
|
||||
- **warnings** — translation gaps: a key missing in some language. The game then falls back to a language that has the text, so nothing breaks; the warning says which line to add.
|
||||
|
||||
## Running it
|
||||
|
||||
```text
|
||||
godot --path . -- --locale-atlas --locale-out=res://tests/artifacts/locale_atlas --with-test-suites
|
||||
```
|
||||
|
||||
It reads every installed mod, writes `report.md` and `report.json` into the `--locale-out` folder, logs a summary line and exits with 1 if there are errors. The test runner has it as the `locale_atlas` test. The text of `report.md` is written in Russian; the problem descriptions are in English.
|
||||
|
||||
A clean run of the current mods:
|
||||
|
||||
```text
|
||||
locale atlas: 2284 key(s), 156 need attention, 0 error(s), 801 warning(s)
|
||||
```
|
||||
|
||||
## A gap and a break, side by side
|
||||
|
||||
To show both kinds, two changes were made to the novel template's mod for one run.
|
||||
|
||||
**A missing translation.** The Spanish line of the town's question was removed from `locale/scenarios_es.properties`. The atlas reports a warning with the line to add:
|
||||
|
||||
```text
|
||||
| warning | `my_novel_game` | `my_novel/town/prompt` | es | `locale/scenarios_en.properties:2` | declared in en, ja, ko, ru, vi, zh but not in 'es' | `locale/scenarios_es.properties: my_novel/town/prompt = Where to go?` |
|
||||
```
|
||||
|
||||
A Spanish player still sees a question — in another language — so this is a gap, not a breakage.
|
||||
|
||||
**A broken reference.** In the town's scenario the key of an answer was misspelt:
|
||||
|
||||
```scenario
|
||||
option "Go into the bar" key=my_novel/town/opt_baar -> :bar
|
||||
```
|
||||
|
||||
Now the key is used but declared in no file, and the atlas reports an **error** for each language, pointing at the scenario line:
|
||||
|
||||
```text
|
||||
| error | `my_novel_game` | `my_novel/town/opt_baar` | ru | `scenarios/my_novel_town.scenario:7` | referenced (scenario, 1×) but declared in no locale file | `locale/scenarios_ru.properties: my_novel/town/opt_baar = …` |
|
||||
```
|
||||
|
||||
The run ended with `7 error(s)` and failed. With the key spelt `opt_bar` again and the Spanish line back, it is clean.
|
||||
|
||||
## What the report contains
|
||||
|
||||
- **Encodings** — every locale file with its encoding, line endings and number of keys; problems such as non-UTF-8, U+FFFD, control characters, mojibake or CR-only line breaks are errors.
|
||||
- **Keys that need attention** — one row per key: a mark per language (`✓` declared, `∅` empty, `—` missing), where it is declared, who refers to it, and what is wrong.
|
||||
- **Problems** — errors and warnings with the mod, key, language, the place to fix and the exact line to add.
|
||||
|
||||
Other warnings: a BOM, mixed line endings, the same key twice with the same value, a mod overriding a key only in some languages, `{0}` placeholders that differ between languages, Cyrillic in English text, `???` in a value, a mod without its `mod_<id>_name` and `mod_<id>_desc`.
|
||||
|
||||
## Where keys come from
|
||||
|
||||
- `.scenario` lines with `key=`; translations of scenario text go to `locale/scenarios_<lang>.properties`;
|
||||
- `Translate("…")`, `Tr("…")` and `Locale = "…"` in C#;
|
||||
- text fields of JSON data (`Name`, `Description`, `title`…), `"@key"` in collections;
|
||||
- auto-translated `text` and `tooltip_text` in `.tscn` scenes;
|
||||
- the manifest's `mod_<id>_name` and `mod_<id>_desc`.
|
||||
|
||||
Locale files must be directly in a mod's `locale/` folder; a file in a subfolder is not read by the game and is an error.
|
||||
|
||||
## If something goes wrong
|
||||
|
||||
1. **An error for a key you see working in English.** The scenario line carries its own text, so the line may still read correctly in one language while the translations of the misspelt key are found nowhere.
|
||||
2. **Hundreds of warnings.** They are translation gaps; each row gives the file and the line to add.
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
# Locale Atlas — cada clave de traducción de cada mod
|
||||
|
||||
El Atlas de localización traza la localización de todos los mods instalados: qué claves declara cada mod en cada idioma, dónde se usan las claves —escenarios, código C#, datos JSON, colecciones, escenas, manifiestos— y qué está mal. Separa dos clases de problemas:
|
||||
|
||||
- **errores** — texto roto: una clave que se usa pero no se declara en ningún sitio, un valor vacío, una clave con dos valores distintos en un mismo mod, un archivo que el cargador no leerá, una codificación dañada;
|
||||
- **advertencias** — huecos de traducción: una clave que falta en algún idioma. El juego entonces recurre a un idioma que tiene el texto, así que nada se rompe; la advertencia dice qué línea añadir.
|
||||
|
||||
## Cómo se ejecuta
|
||||
|
||||
```text
|
||||
godot --path . -- --locale-atlas --locale-out=res://tests/artifacts/locale_atlas --with-test-suites
|
||||
```
|
||||
|
||||
Lee todos los mods instalados, escribe `report.md` y `report.json` en la carpeta `--locale-out`, registra una línea de resumen y sale con 1 si hay errores. El test runner lo tiene como la prueba `locale_atlas`. El texto de `report.md` está escrito en ruso; las descripciones de los problemas, en inglés.
|
||||
|
||||
Una ejecución limpia de los mods actuales:
|
||||
|
||||
```text
|
||||
locale atlas: 2284 key(s), 156 need attention, 0 error(s), 801 warning(s)
|
||||
```
|
||||
|
||||
## Un hueco y una rotura, lado a lado
|
||||
|
||||
Para mostrar las dos clases, se hicieron dos cambios en el mod de la plantilla de novela durante una ejecución.
|
||||
|
||||
**Una traducción que falta.** Se quitó de `locale/scenarios_es.properties` la línea en español de la pregunta del pueblo. El atlas informa de una advertencia con la línea que hay que añadir:
|
||||
|
||||
```text
|
||||
| warning | `my_novel_game` | `my_novel/town/prompt` | es | `locale/scenarios_en.properties:2` | declared in en, ja, ko, ru, vi, zh but not in 'es' | `locale/scenarios_es.properties: my_novel/town/prompt = Where to go?` |
|
||||
```
|
||||
|
||||
Un jugador español sigue viendo una pregunta —en otro idioma—, así que esto es un hueco, no una rotura.
|
||||
|
||||
**Una referencia rota.** En el escenario del pueblo se equivocó la grafía de la clave de una respuesta:
|
||||
|
||||
```scenario
|
||||
option "Go into the bar" key=my_novel/town/opt_baar -> :bar
|
||||
```
|
||||
|
||||
Ahora la clave se usa pero no se declara en ningún archivo, y el atlas informa de un **error** por cada idioma, señalando la línea del escenario:
|
||||
|
||||
```text
|
||||
| error | `my_novel_game` | `my_novel/town/opt_baar` | ru | `scenarios/my_novel_town.scenario:7` | referenced (scenario, 1×) but declared in no locale file | `locale/scenarios_ru.properties: my_novel/town/opt_baar = …` |
|
||||
```
|
||||
|
||||
La ejecución terminó con `7 error(s)` y falló. Con la clave escrita de nuevo como `opt_bar` y la línea en español de vuelta, queda limpio.
|
||||
|
||||
## Qué contiene el informe
|
||||
|
||||
- **Codificaciones** — cada archivo de localización con su codificación, fines de línea y número de claves; problemas como no-UTF-8, U+FFFD, caracteres de control, mojibake o fines de línea solo con CR son errores.
|
||||
- **Claves que requieren atención** — una fila por clave: una marca por idioma (`✓` declarada, `∅` vacía, `—` ausente), dónde se declara, quién la referencia y qué está mal.
|
||||
- **Problemas** — errores y advertencias con el mod, la clave, el idioma, el sitio que corregir y la línea exacta que añadir.
|
||||
|
||||
Otras advertencias: un BOM, fines de línea mezclados, la misma clave dos veces con el mismo valor, un mod que sustituye una clave solo en algunos idiomas, marcadores `{0}` que difieren entre idiomas, cirílico en texto inglés, `???` en un valor, un mod sin su `mod_<id>_name` y `mod_<id>_desc`.
|
||||
|
||||
## De dónde salen las claves
|
||||
|
||||
- líneas `.scenario` con `key=`; las traducciones del texto del escenario van a `locale/scenarios_<lang>.properties`;
|
||||
- `Translate("…")`, `Tr("…")` y `Locale = "…"` en C#;
|
||||
- campos de texto de los datos JSON (`Name`, `Description`, `title`…), `"@key"` en colecciones;
|
||||
- `text` y `tooltip_text` autotraducidos en las escenas `.tscn`;
|
||||
- el `mod_<id>_name` y el `mod_<id>_desc` del manifiesto.
|
||||
|
||||
Los archivos de localización deben estar directamente en la carpeta `locale/` del mod; un archivo en una subcarpeta no lo lee el juego y es un error.
|
||||
|
||||
## Si algo va mal
|
||||
|
||||
1. **Un error para una clave que ves funcionar en inglés.** La línea del escenario lleva su propio texto, así que puede leerse correctamente en un idioma mientras las traducciones de la clave mal escrita no aparecen en ningún sitio.
|
||||
2. **Cientos de advertencias.** Son huecos de traducción; cada fila da el archivo y la línea que añadir.
|
||||
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
# Locale Atlas — すべての MOD のすべての翻訳キー
|
||||
|
||||
Locale Atlas は、インストール済み全 MOD のローカライズを地図にします。どの MOD がどの言語でどのキーを宣言しているか、キーがどこで使われているか——シナリオ、C# コード、JSON データ、コレクション、シーン、マニフェスト——そして何がおかしいか。問題を 2 種類に分けます:
|
||||
|
||||
- **エラー** — 壊れたテキスト。使われているのにどこにも宣言されていないキー、空の値、同じ MOD 内で 2 つの異なる値を持つキー、ローダーが読めないファイル、壊れたエンコーディング;
|
||||
- **警告** — 翻訳の欠け。ある言語で欠けているキー。この場合、ゲームはテキストがある言語へフォールバックするので、何も壊れません。警告には足すべき行が示されます。
|
||||
|
||||
## 実行方法
|
||||
|
||||
```text
|
||||
godot --path . -- --locale-atlas --locale-out=res://tests/artifacts/locale_atlas --with-test-suites
|
||||
```
|
||||
|
||||
インストール済みの全 MOD を読み、`report.md` と `report.json` を `--locale-out` フォルダーに書き込み、サマリー行をログに出し、エラーがあれば終了コード 1 で終わります。テストランナーでは `locale_atlas` テストです。`report.md` の本文はロシア語、問題の説明は英語です。
|
||||
|
||||
現在の MOD のきれいな実行:
|
||||
|
||||
```text
|
||||
locale atlas: 2284 key(s), 156 need attention, 0 error(s), 801 warning(s)
|
||||
```
|
||||
|
||||
## 欠けと壊れを並べて見る
|
||||
|
||||
2 種類を見せるために、小説テンプレートの MOD に 1 回の実行のための変更を 2 か所加えました。
|
||||
|
||||
**欠けている翻訳。** 町の質問のスペイン語行を `locale/scenarios_es.properties` から削除しました。アトラスは、足すべき行とともに警告を報告します:
|
||||
|
||||
```text
|
||||
| warning | `my_novel_game` | `my_novel/town/prompt` | es | `locale/scenarios_en.properties:2` | declared in en, ja, ko, ru, vi, zh but not in 'es' | `locale/scenarios_es.properties: my_novel/town/prompt = Where to go?` |
|
||||
```
|
||||
|
||||
スペイン語のプレイヤーにはそれでも質問が見えます——ただし別の言語で——。つまりこれは欠けであり、壊れではありません。
|
||||
|
||||
**壊れた参照。** 町のシナリオで、ある回答のキーのつづりを間違えました:
|
||||
|
||||
```scenario
|
||||
option "Go into the bar" key=my_novel/town/opt_baar -> :bar
|
||||
```
|
||||
|
||||
このキーは使われているのにどのファイルにも宣言されておらず、アトラスは言語ごとに**エラー**を報告し、シナリオの行を指します:
|
||||
|
||||
```text
|
||||
| error | `my_novel_game` | `my_novel/town/opt_baar` | ru | `scenarios/my_novel_town.scenario:7` | referenced (scenario, 1×) but declared in no locale file | `locale/scenarios_ru.properties: my_novel/town/opt_baar = …` |
|
||||
```
|
||||
|
||||
実行は `7 error(s)` で終わり、失敗しました。キーを再び `opt_bar` とつづり、スペイン語行を戻せば、またきれいになります。
|
||||
|
||||
## レポートの中身
|
||||
|
||||
- **エンコーディング** — ローカライズファイルごとのエンコーディング、改行、キー数。非 UTF-8、U+FFFD、制御文字、文字化け（mojibake）、CR のみの改行はエラーです。
|
||||
- **注意が必要なキー** — キーごとに 1 行。言語ごとの印（`✓` 宣言済み、`∅` 空、`—` 欠落）、宣言場所、参照している箇所、そして何がおかしいか。
|
||||
- **問題** — MOD・キー・言語・直す場所・足すべき正確な行つきの、エラーと警告。
|
||||
|
||||
その他の警告: BOM、混在する改行、同じ値で 2 回現れる同じキー、一部の言語だけでキーを上書きする MOD、言語間で異なる `{0}` プレースホルダー、英語テキスト内のキリル文字、値の中の `???`、`mod_<id>_name` と `mod_<id>_desc` のない MOD。
|
||||
|
||||
## キーはどこから来るか
|
||||
|
||||
- `key=` の付いた `.scenario` 行。シナリオテキストの翻訳は `locale/scenarios_<lang>.properties` へ;
|
||||
- C# の `Translate("…")`、`Tr("…")`、`Locale = "…"`;
|
||||
- JSON データのテキスト欄（`Name`、`Description`、`title` など）、コレクションの `"@key"`;
|
||||
- `.tscn` シーンで自動翻訳される `text` と `tooltip_text`;
|
||||
- マニフェストの `mod_<id>_name` と `mod_<id>_desc`。
|
||||
|
||||
ローカライズファイルは MOD の `locale/` フォルダー直下になければなりません。サブフォルダー内のファイルはゲームに読まれず、エラーです。
|
||||
|
||||
## 何かがおかしいとき
|
||||
|
||||
1. **英語では正しく見えるキーにエラー。** シナリオ行は自分のテキストを運ぶので、つづりを間違えたキーの翻訳がどこにも見つからないまま、ある言語では正しく読めることがあります。
|
||||
2. **何百もの警告。** これらは翻訳の欠けです。各行が、足すべきファイルと行を示します。
|
||||
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
# Locale Atlas — 모든 모드의 모든 번역 키
|
||||
|
||||
Locale Atlas는 설치된 모든 모드의 현지화를 지도로 만듭니다. 각 모드가 각 언어로 어떤 키를 선언하는지, 키가 어디서 쓰이는지—시나리오, C# 코드, JSON 데이터, 컬렉션, 씬, 매니페스트—그리고 무엇이 잘못되었는지 보여 줍니다. 문제를 두 종류로 나눕니다:
|
||||
|
||||
- **오류** — 깨진 텍스트. 쓰이지만 어디에도 선언되지 않은 키, 빈 값, 한 모드 안에서 두 개의 다른 값을 가진 키, 로더가 읽지 못할 파일, 깨진 인코딩;
|
||||
- **경고** — 번역 공백. 어떤 언어에서 빠진 키. 이때 게임은 텍스트가 있는 언어로 되돌아가므로 아무것도 깨지지 않고, 경고는 채워 넣을 줄을 알려 줍니다.
|
||||
|
||||
## 실행 방법
|
||||
|
||||
```text
|
||||
godot --path . -- --locale-atlas --locale-out=res://tests/artifacts/locale_atlas --with-test-suites
|
||||
```
|
||||
|
||||
설치된 모든 모드를 읽고, `report.md`와 `report.json`을 `--locale-out` 폴더에 쓰고, 요약 줄을 로그에 남기며, 오류가 있으면 종료 코드 1로 끝납니다. 테스트 러너에서는 `locale_atlas` 테스트입니다. `report.md`의 본문은 러시아어이고, 문제 설명은 영어입니다.
|
||||
|
||||
현재 모드들의 깨끗한 실행:
|
||||
|
||||
```text
|
||||
locale atlas: 2284 key(s), 156 need attention, 0 error(s), 801 warning(s)
|
||||
```
|
||||
|
||||
## 공백과 고장, 나란히 놓고 보기
|
||||
|
||||
두 종류를 보여 드리기 위해, 한 번의 실행을 위해 소설 템플릿의 모드에 두 가지 변경을 했습니다.
|
||||
|
||||
**빠진 번역.** 마을 질문의 스페인어 줄을 `locale/scenarios_es.properties`에서 지웠습니다. 아틀라스는 채워 넣을 줄과 함께 경고를 보고합니다:
|
||||
|
||||
```text
|
||||
| warning | `my_novel_game` | `my_novel/town/prompt` | es | `locale/scenarios_en.properties:2` | declared in en, ja, ko, ru, vi, zh but not in 'es' | `locale/scenarios_es.properties: my_novel/town/prompt = Where to go?` |
|
||||
```
|
||||
|
||||
스페인어 플레이어에게도 여전히 질문이 보입니다—다른 언어로—그러니 이것은 고장이 아니라 공백입니다.
|
||||
|
||||
**깨진 참조.** 마을 시나리오에서 한 답변의 키 철자를 틀렸습니다:
|
||||
|
||||
```scenario
|
||||
option "Go into the bar" key=my_novel/town/opt_baar -> :bar
|
||||
```
|
||||
|
||||
이제 이 키는 쓰이지만 어느 파일에도 선언되지 않았고, 아틀라스는 언어마다 하나씩 **오류**를 보고하며 시나리오의 그 줄을 가리킵니다:
|
||||
|
||||
```text
|
||||
| error | `my_novel_game` | `my_novel/town/opt_baar` | ru | `scenarios/my_novel_town.scenario:7` | referenced (scenario, 1×) but declared in no locale file | `locale/scenarios_ru.properties: my_novel/town/opt_baar = …` |
|
||||
```
|
||||
|
||||
실행은 `7 error(s)`로 끝났고 실패했습니다. 키를 다시 `opt_bar`로 쓰고 스페인어 줄을 돌려 놓으면 다시 깨끗해집니다.
|
||||
|
||||
## 리포트에 든 것
|
||||
|
||||
- **인코딩** — 로컬라이즈 파일마다 인코딩, 줄바꿈, 키 수. 비(非) UTF-8, U+FFFD, 제어 문자, mojibake, CR 전용 줄바꿈 같은 문제는 오류입니다.
|
||||
- **주의가 필요한 키** — 키마다 한 행. 언어별 표식(`✓` 선언됨, `∅` 비었음, `—` 없음), 선언 위치, 참조하는 곳, 그리고 무엇이 잘못되었는지.
|
||||
- **문제** — 모드·키·언어·고칠 위치·채워 넣을 정확한 줄이 붙은 오류와 경고.
|
||||
|
||||
그 밖의 경고: BOM, 뒤섞인 줄바꿈, 같은 값으로 두 번 나오는 같은 키, 일부 언어에서만 키를 재정의하는 모드, 언어 사이가 다른 `{0}` 자리표시자, 영어 텍스트 속 키릴 문자, 값 속의 `???`, `mod_<id>_name`과 `mod_<id>_desc`가 없는 모드.
|
||||
|
||||
## 키는 어디서 오는가
|
||||
|
||||
- `key=`가 붙은 `.scenario` 줄. 시나리오 텍스트의 번역은 `locale/scenarios_<lang>.properties`로 갑니다;
|
||||
- C#의 `Translate("…")`, `Tr("…")`, `Locale = "…"`;
|
||||
- JSON 데이터의 텍스트 필드(`Name`, `Description`, `title`…), 컬렉션의 `"@key"`;
|
||||
- `.tscn` 씬에서 자동 번역되는 `text`와 `tooltip_text`;
|
||||
- 매니페스트의 `mod_<id>_name`과 `mod_<id>_desc`.
|
||||
|
||||
로컬라이즈 파일은 모드의 `locale/` 폴더 바로 아래에 있어야 합니다. 하위 폴더의 파일은 게임이 읽지 않으며 오류입니다.
|
||||
|
||||
## 무언가 잘못되었을 때
|
||||
|
||||
1. **영어에서는 멀쩡히 보이는 키에 오류.** 시나리오 줄은 자기 텍스트를 직접 담고 있으므로, 철자가 틀린 키의 번역이 어디에도 없는데도 한 언어에서는 올바르게 읽힐 수 있습니다.
|
||||
2. **수백 개의 경고.** 번역 공백입니다. 각 행이 채워 넣을 파일과 줄을 알려 줍니다.
|
||||
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
# Locale Atlas — каждый ключ перевода каждого мода
|
||||
|
||||
Карта локализации раскладывает локализацию всех установленных модов: какие ключи каждый мод объявляет на каждом языке, где ключи используются — в сценариях, коде C#, данных JSON, коллекциях, сценах, манифестах — и что не так. Она разделяет два вида проблем:
|
||||
|
||||
- **ошибки** — сломанный текст: ключ, который используется, но нигде не объявлен; пустое значение; один ключ с двумя разными значениями в одном моде; файл, который загрузчик не прочтёт; испорченная кодировка;
|
||||
- **предупреждения** — пробелы в переводе: ключ, отсутствующий на каком-то языке. Игра тогда откатывается к языку, где текст есть, так что ничего не ломается; в предупреждении сказано, какую строку добавить.
|
||||
|
||||
## Как запустить
|
||||
|
||||
```text
|
||||
godot --path . -- --locale-atlas --locale-out=res://tests/artifacts/locale_atlas --with-test-suites
|
||||
```
|
||||
|
||||
Она читает каждый установленный мод, пишет `report.md` и `report.json` в папку `--locale-out`, выводит в лог итоговую строку и завершается с кодом 1, если есть ошибки. В тест-раннере это тест `locale_atlas`. Текст `report.md` написан по-русски; описания проблем — на английском.
|
||||
|
||||
Чистый запуск текущих модов:
|
||||
|
||||
```text
|
||||
locale atlas: 2284 key(s), 156 need attention, 0 error(s), 801 warning(s)
|
||||
```
|
||||
|
||||
## Пробел и поломка бок о бок
|
||||
|
||||
Чтобы показать оба вида, для одного запуска в мод шаблона новеллы внесли две правки.
|
||||
|
||||
**Отсутствующий перевод.** Из `locale/scenarios_es.properties` убрали испанскую строку вопроса города. Атлас сообщает предупреждение со строкой, которую надо добавить:
|
||||
|
||||
```text
|
||||
| warning | `my_novel_game` | `my_novel/town/prompt` | es | `locale/scenarios_en.properties:2` | declared in en, ja, ko, ru, vi, zh but not in 'es' | `locale/scenarios_es.properties: my_novel/town/prompt = Where to go?` |
|
||||
```
|
||||
|
||||
Испанский игрок всё же видит вопрос — на другом языке, — так что это пробел, а не поломка.
|
||||
|
||||
**Сломанная ссылка.** В сценарии города в ключе одного из ответов сделали опечатку:
|
||||
|
||||
```scenario
|
||||
option "Go into the bar" key=my_novel/town/opt_baar -> :bar
|
||||
```
|
||||
|
||||
Теперь ключ используется, но не объявлен ни в одном файле, и атлас сообщает **ошибку** для каждого языка, указывая на строку сценария:
|
||||
|
||||
```text
|
||||
| error | `my_novel_game` | `my_novel/town/opt_baar` | ru | `scenarios/my_novel_town.scenario:7` | referenced (scenario, 1×) but declared in no locale file | `locale/scenarios_ru.properties: my_novel/town/opt_baar = …` |
|
||||
```
|
||||
|
||||
Запуск кончился `7 error(s)` и провалился. Стоило снова написать ключ `opt_bar` и вернуть испанскую строку, как всё стало чисто.
|
||||
|
||||
## Что внутри отчёта
|
||||
|
||||
- **Кодировки** — каждый файл локализации с его кодировкой, переводами строк и числом ключей; проблемы вроде не-UTF-8, U+FFFD, управляющих символов, mojibake или переводов строк только с CR — это ошибки.
|
||||
- **Ключи, требующие внимания** — по строке на ключ: отметка на каждый язык (`✓` объявлен, `∅` пуст, `—` отсутствует), где он объявлен, кто на него ссылается и что не так.
|
||||
- **Проблемы** — ошибки и предупреждения с модом, ключом, языком, местом правки и точной строкой, которую надо добавить.
|
||||
|
||||
Другие предупреждения: BOM, смешанные переводы строк, один и тот же ключ дважды с одним значением, мод, переопределяющий ключ только на части языков, несовпадающие между языками заполнители `{0}`, кириллица в английском тексте, `???` в значении, мод без своих `mod_<id>_name` и `mod_<id>_desc`.
|
||||
|
||||
## Откуда берутся ключи
|
||||
|
||||
- строки `.scenario` с `key=`; переводы текста сценария идут в `locale/scenarios_<lang>.properties`;
|
||||
- `Translate("…")`, `Tr("…")` и `Locale = "…"` в C#;
|
||||
- текстовые поля данных JSON (`Name`, `Description`, `title`…), `"@key"` в коллекциях;
|
||||
- автопереведённые `text` и `tooltip_text` в сценах `.tscn`;
|
||||
- `mod_<id>_name` и `mod_<id>_desc` из манифеста.
|
||||
|
||||
Файлы локализации должны лежать прямо в папке `locale/` мода; файл во вложенной папке игра не читает, и это ошибка.
|
||||
|
||||
## Если что-то пошло не так
|
||||
|
||||
1. **Ошибка для ключа, который по-английски работает.** Строка сценария несёт собственный текст, поэтому на одном языке всё может выглядеть правильно, тогда как переводы опечатанного ключа не находятся нигде.
|
||||
2. **Сотни предупреждений.** Это пробелы перевода; каждая строка даёт файл и строку, которую надо добавить.
|
||||
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
# Locale Atlas — mọi khóa dịch của mọi mod
|
||||
|
||||
Locale Atlas vẽ ra phần bản địa hóa của mọi mod đã cài: mỗi mod khai báo những khóa nào ở mỗi ngôn ngữ, các khóa được dùng ở đâu — kịch bản, mã C#, dữ liệu JSON, bộ sưu tập, cảnh, manifest — và cái gì không ổn. Nó tách thành hai loại vấn đề:
|
||||
|
||||
- **lỗi** — văn bản hỏng: một khóa được dùng nhưng không khai báo ở đâu cả, một giá trị rỗng, một khóa có hai giá trị khác nhau trong cùng một mod, một tệp mà bộ nạp không đọc được, mã hóa hỏng;
|
||||
- **cảnh báo** — chỗ thiếu bản dịch: một khóa còn thiếu ở ngôn ngữ nào đó. Khi đó game sẽ quay về một ngôn ngữ có sẵn đoạn chữ, nên chẳng có gì vỡ; cảnh báo cho biết cần thêm dòng nào.
|
||||
|
||||
## Cách chạy
|
||||
|
||||
```text
|
||||
godot --path . -- --locale-atlas --locale-out=res://tests/artifacts/locale_atlas --with-test-suites
|
||||
```
|
||||
|
||||
Nó đọc mọi mod đã cài, ghi `report.md` và `report.json` vào thư mục `--locale-out`, ghi một dòng tổng kết vào log và thoát với mã 1 nếu có lỗi. Trong test runner, nó là phép kiểm thử `locale_atlas`. Phần chữ của `report.md` viết bằng tiếng Nga; phần mô tả vấn đề viết bằng tiếng Anh.
|
||||
|
||||
Một lần chạy sạch với các mod hiện có:
|
||||
|
||||
```text
|
||||
locale atlas: 2284 key(s), 156 need attention, 0 error(s), 801 warning(s)
|
||||
```
|
||||
|
||||
## Một chỗ thiếu và một chỗ hỏng, đặt cạnh nhau
|
||||
|
||||
Để thấy cả hai loại, người ta sửa hai chỗ trong mod của bản mẫu tiểu thuyết cho đúng một lần chạy.
|
||||
|
||||
**Một bản dịch bị thiếu.** Dòng tiếng Tây Ban Nha của câu hỏi thị trấn đã bị xóa khỏi `locale/scenarios_es.properties`. Atlas báo một cảnh báo kèm dòng cần thêm:
|
||||
|
||||
```text
|
||||
| warning | `my_novel_game` | `my_novel/town/prompt` | es | `locale/scenarios_en.properties:2` | declared in en, ja, ko, ru, vi, zh but not in 'es' | `locale/scenarios_es.properties: my_novel/town/prompt = Where to go?` |
|
||||
```
|
||||
|
||||
Người chơi tiếng Tây Ban Nha vẫn thấy một câu hỏi — bằng một ngôn ngữ khác — nên đây là chỗ thiếu, không phải chỗ hỏng.
|
||||
|
||||
**Một tham chiếu bị hỏng.** Trong kịch bản của thị trấn, khóa của một câu trả lời bị gõ nhầm chính tả:
|
||||
|
||||
```scenario
|
||||
option "Go into the bar" key=my_novel/town/opt_baar -> :bar
|
||||
```
|
||||
|
||||
Giờ khóa này được dùng nhưng không được khai báo trong tệp nào, và Atlas báo một **lỗi** cho mỗi ngôn ngữ, chỉ thẳng vào dòng kịch bản:
|
||||
|
||||
```text
|
||||
| error | `my_novel_game` | `my_novel/town/opt_baar` | ru | `scenarios/my_novel_town.scenario:7` | referenced (scenario, 1×) but declared in no locale file | `locale/scenarios_ru.properties: my_novel/town/opt_baar = …` |
|
||||
```
|
||||
|
||||
Lần chạy ấy kết thúc với `7 error(s)` và thất bại. Gõ lại khóa là `opt_bar` và trả lại dòng tiếng Tây Ban Nha thì mọi thứ sạch sẽ trở lại.
|
||||
|
||||
## Báo cáo chứa gì
|
||||
|
||||
- **Mã hóa** — mỗi tệp bản địa hóa kèm mã hóa, kiểu xuống dòng và số khóa; các vấn đề như không phải UTF-8, U+FFFD, ký tự điều khiển, mojibake hoặc xuống dòng chỉ có CR đều là lỗi.
|
||||
- **Các khóa cần chú ý** — mỗi khóa một dòng: một dấu cho mỗi ngôn ngữ (`✓` đã khai báo, `∅` rỗng, `—` thiếu), khai báo ở đâu, ai tham chiếu đến nó, và cái gì không ổn.
|
||||
- **Vấn đề** — lỗi và cảnh báo kèm mod, khóa, ngôn ngữ, chỗ cần sửa và dòng chính xác cần thêm.
|
||||
|
||||
Các cảnh báo khác: BOM, kiểu xuống dòng trộn lẫn, cùng một khóa xuất hiện hai lần với cùng một giá trị, một mod chỉ ghi đè khóa ở một số ngôn ngữ, trình giữ chỗ `{0}` không khớp giữa các ngôn ngữ, chữ Cyrillic trong văn bản tiếng Anh, `???` trong một giá trị, một mod thiếu `mod_<id>_name` và `mod_<id>_desc` của nó.
|
||||
|
||||
## Khóa đến từ đâu
|
||||
|
||||
- các dòng `.scenario` có `key=`; bản dịch của văn bản kịch bản đi vào `locale/scenarios_<lang>.properties`;
|
||||
- `Translate("…")`, `Tr("…")` và `Locale = "…"` trong C#;
|
||||
- các trường văn bản của dữ liệu JSON (`Name`, `Description`, `title`…), `"@key"` trong bộ sưu tập;
|
||||
- `text` và `tooltip_text` được tự động dịch trong các cảnh `.tscn`;
|
||||
- `mod_<id>_name` và `mod_<id>_desc` của manifest.
|
||||
|
||||
Tệp bản địa hóa phải nằm ngay trong thư mục `locale/` của mod; tệp trong thư mục con không được game đọc và được tính là lỗi.
|
||||
|
||||
## Nếu có gì đó không ổn
|
||||
|
||||
1. **Một lỗi cho khóa mà bạn thấy chạy tốt trong tiếng Anh.** Dòng kịch bản tự mang văn bản của nó, nên nó vẫn có thể đọc đúng ở một ngôn ngữ trong khi bản dịch của khóa gõ nhầm không tìm thấy ở đâu cả.
|
||||
2. **Hàng trăm cảnh báo.** Đó là những chỗ thiếu bản dịch; mỗi dòng đều cho biết tệp và dòng cần thêm.
|
||||
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
# Locale Atlas — 每个模组的每一个翻译键
|
||||
|
||||
本地化图谱描绘所有已安装模组的本地化情况：每个模组在每种语言里声明了哪些键、这些键在哪里被使用——剧情、C# 代码、JSON 数据、合集、场景、清单——以及哪里出了问题。它把问题分成两类：
|
||||
|
||||
- **错误** — 文本损坏：一个键被使用却没有在任何地方声明；值为空；同一个键在同一个模组里有两个不同的值；加载器读不了的文件；损坏的编码；
|
||||
- **警告** — 翻译缺口：某个键在某门语言里缺失。这时游戏会回退到有这段文本的语言，所以什么都不会坏；警告会说明该添加哪一行。
|
||||
|
||||
## 如何运行
|
||||
|
||||
```text
|
||||
godot --path . -- --locale-atlas --locale-out=res://tests/artifacts/locale_atlas --with-test-suites
|
||||
```
|
||||
|
||||
它读取每个已安装的模组，把 `report.md` 和 `report.json` 写进 `--locale-out` 文件夹，在日志里输出一行汇总，并在有错误时以退出码 1 结束。测试运行器把它当作 `locale_atlas` 测试。`report.md` 的正文是俄语，问题描述是英语。
|
||||
|
||||
对当前各模组的一次干净运行：
|
||||
|
||||
```text
|
||||
locale atlas: 2284 key(s), 156 need attention, 0 error(s), 801 warning(s)
|
||||
```
|
||||
|
||||
## 缺口与损坏，并排来看
|
||||
|
||||
为了展示这两类问题，在小说模板的模组里为一次运行做了两处改动。
|
||||
|
||||
**缺失的翻译。** 小镇问题那一行西班牙语从 `locale/scenarios_es.properties` 里被删掉了。图谱报告一条警告，并给出该添加的行：
|
||||
|
||||
```text
|
||||
| warning | `my_novel_game` | `my_novel/town/prompt` | es | `locale/scenarios_en.properties:2` | declared in en, ja, ko, ru, vi, zh but not in 'es' | `locale/scenarios_es.properties: my_novel/town/prompt = Where to go?` |
|
||||
```
|
||||
|
||||
西班牙语玩家仍然会看到一个提问——不过是另一种语言的——所以这是缺口，而不是损坏。
|
||||
|
||||
**损坏的引用。** 在小镇的剧情里，一个答案的键拼错了：
|
||||
|
||||
```scenario
|
||||
option "Go into the bar" key=my_novel/town/opt_baar -> :bar
|
||||
```
|
||||
|
||||
现在这个键被使用，却没有在任何文件里声明，图谱对每种语言各报告一条**错误**，并指向剧情里的那一行：
|
||||
|
||||
```text
|
||||
| error | `my_novel_game` | `my_novel/town/opt_baar` | ru | `scenarios/my_novel_town.scenario:7` | referenced (scenario, 1×) but declared in no locale file | `locale/scenarios_ru.properties: my_novel/town/opt_baar = …` |
|
||||
```
|
||||
|
||||
那次运行以 `7 error(s)` 结束并失败。把键重新拼成 `opt_bar`、把西班牙语那行加回来之后，一切又干净了。
|
||||
|
||||
## 报告里有什么
|
||||
|
||||
- **编码** — 每个本地化文件的编码、换行符和键数；非 UTF-8、U+FFFD、控制字符、乱码（mojibake）或仅用 CR 换行等问题都属于错误。
|
||||
- **需要关注的键** — 每个键一行：每种语言一个标记（`✓` 已声明、`∅` 为空、`—` 缺失），在哪里声明、谁在引用它、哪里有问题。
|
||||
- **问题** — 错误和警告，附模组、键、语言、要修改的位置以及要添加的准确一行。
|
||||
|
||||
其他警告：BOM、混杂的换行符、同一个键以相同的值出现两次、模组只在部分语言里覆盖某个键、各语言之间不一致的 `{0}` 占位符、英文文本里出现西里尔字母、值里出现 `???`，以及模组缺少自己的 `mod_<id>_name` 和 `mod_<id>_desc`。
|
||||
|
||||
## 键从哪里来
|
||||
|
||||
- 带 `key=` 的 `.scenario` 行；剧情文本的翻译进入 `locale/scenarios_<lang>.properties`；
|
||||
- C# 里的 `Translate("…")`、`Tr("…")` 和 `Locale = "…"`；
|
||||
- JSON 数据的文本字段（`Name`、`Description`、`title`……），合集里的 `"@key"`；
|
||||
- `.tscn` 场景里自动翻译的 `text` 和 `tooltip_text`；
|
||||
- 清单里的 `mod_<id>_name` 和 `mod_<id>_desc`。
|
||||
|
||||
本地化文件必须直接放在模组的 `locale/` 文件夹里；子文件夹里的文件游戏读不到，算一个错误。
|
||||
|
||||
## 如果出了问题
|
||||
|
||||
1. **某个键在英语里明明正常，却报了错误。** 剧情行自带文本，所以它在一种语言里可能仍然显示正常，而拼错的键的翻译却哪里都找不到。
|
||||
2. **成百上千条警告。** 它们是翻译缺口；每一行都给出文件名和该添加的那一行。
|
||||
|
||||
Reference in new issue
Block a user