Skip to content

OpenToonz - An open-source full-featured 2D animation creation software

C

Document translation contribution and maintenance workflows

Rodneydb4c979d48ef
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1e8e574dd..2503b093a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,14 +51,13 @@ to keep the issue tracker from becoming cluttered with unfulfilled feature reque
## Translations
-Translation source (`.ts`) files for OpenToonz GUI are located in `toonz/sources/translations`.
-If you create new `.ts` files for your language or update an existing one,
-please send us those modifications as pull-requests.
-[Qt Linguist](http://doc.qt.io/qt-5.6/linguist-translators.html) is useful for translating them.
-
-Please send us Qt message (`.qm`) files with `.ts` files if you can make the following modifications.
-
-OpenToonz uses `.qm` files generated from `.ts` files.
-You can generate `.qm` files by using [Qt Linguist](http://doc.qt.io/qt-5.6/linguist-translators.html).
-Please locate generated `.qm` files in `stuff/config/loc`.
-It enables the OpenToonz installer to install them into the `stuff` directory.
+Translation sources (`.ts`) are in `toonz/sources/translations`. Contributors can
+edit them with Qt Linguist and submit a PR, or attach the updated files to an
+issue/discussion for a maintainer to integrate. A full application build is not
+required to contribute wording. Share editable sources; compiled `.qm` files are
+optional test artifacts unless a maintainer requests them.
+
+See [Contributing and maintaining translations](toonz/sources/translations/README.md)
+for the two workflows: sharing translations, and reviewing/merging/updating them.
+The guide includes existing Qt Linguist, shell-script, and CMake/Visual Studio
+processes, validation, runtime paths, and packaging checks.
diff --git a/README.md b/README.md
index 01c2eb596..b3705f55d 100644
--- a/README.md
+++ b/README.md
@@ -68,3 +68,9 @@ Can't develop but still want to help? Help us test individual Pull Requests befo
### Special Thanks
This open-source program is developed from Toonz, a software originally created by Digital Video, S.p.A., Rome, Italy
+
+## Contributing translations
+
+To share updated translation files or review, merge, and refresh catalogs, see
+[Contributing and maintaining translations](toonz/sources/translations/README.md).
+Qt Linguist editing and existing manual translation tools remain supported.
diff --git a/doc/README_chs.md b/doc/README_chs.md
index 42ce16284..0eb558089 100644
--- a/doc/README_chs.md
+++ b/doc/README_chs.md
@@ -59,3 +59,8 @@ OpenToonz 是一个由[DWANGO](http://dwango.co.jp/english/)公开发布的二
### 特别感谢
原始程序从Toonz开发而来,这是一个由意大利罗马的公司 Digital Video, S.p.A.所开发的软件。
+
+## 参与翻译
+
+有关提交翻译文件以及审核、合并和更新翻译的流程,请参阅
+[翻译指南(英文)](../toonz/sources/translations/README.md)。
diff --git a/doc/README_ja.md b/doc/README_ja.md
index ce968f66f..b71e14b7d 100644
--- a/doc/README_ja.md
+++ b/doc/README_ja.md
@@ -47,4 +47,8 @@
- 各ディレクトリ内の README やソースコードに記載されたライセンスに従ってください
### Special Thanks
-This open-source program is developed from Toonz, a software originally created by Digital Video, S.p.A., Rome, Italy
\ No newline at end of file
+This open-source program is developed from Toonz, a software originally created by Digital Video, S.p.A., Rome, Italy
+## 翻訳への貢献
+
+翻訳ファイルの提出、レビュー、マージ、更新については、
+[翻訳ガイド(英語)](../toonz/sources/translations/README.md)を参照してください。
diff --git a/doc/how_to_build_bsd.md b/doc/how_to_build_bsd.md
index 2f988ad79..c1e4fb7f3 100644
--- a/doc/how_to_build_bsd.md
+++ b/doc/how_to_build_bsd.md
@@ -29,3 +29,10 @@ Notes:
Continue the instructions as stated in [the linux guide](https://github.com/opentoonz/opentoonz/blob/master/doc/how_to_build_linux.md) to finish the compilation.
+
+## Translation workflow
+
+See [Contributing and maintaining translations](../toonz/sources/translations/README.md)
+for editing/submitting `.ts` files, explicit extraction targets, manual `lrelease`,
+and package/runtime paths. Translation-only edits may not refresh catalogs through
+an otherwise no-op application build; confirm the affected `.qm` was regenerated.
diff --git a/doc/how_to_build_linux.md b/doc/how_to_build_linux.md
index ac589740a..182312a3e 100644
--- a/doc/how_to_build_linux.md
+++ b/doc/how_to_build_linux.md
@@ -190,3 +190,10 @@ It may be helpful to use existing packages as a reference when creating a packag
- App-Image (Portable):
https://github.com/morevnaproject/morevna-builds
+
+## Translation workflow
+
+See [Contributing and maintaining translations](../toonz/sources/translations/README.md)
+for editing/submitting `.ts` files, explicit extraction targets, manual `lrelease`,
+and package/runtime paths. Translation-only edits may not refresh catalogs through
+an otherwise no-op application build; confirm the affected `.qm` was regenerated.
diff --git a/doc/how_to_build_macosx.md b/doc/how_to_build_macosx.md
index 148c53673..8873e38e0 100644
--- a/doc/how_to_build_macosx.md
+++ b/doc/how_to_build_macosx.md
@@ -136,3 +136,11 @@ open ~/Documents/opentoonz/build/toonz/OpenToonz.app
- Run in Debug mode: Product -> Run
- To open with command line or from Finder window, the application is found in `/Users/yourlogin/Documents/opentoonz/toonz/build/Debug/OpenToonz.app`
+
+## Translation workflow / 翻訳
+
+See [Contributing and maintaining translations](../toonz/sources/translations/README.md)
+for contributor and maintainer workflows. Keep the Xcode `WITH_TRANSLATION=OFF`
+workaround above until translation-enabled Xcode builds are verified. That option
+disables this build's translation generation; do not assume bundled catalogs were
+updated. Qt Linguist and manual `lrelease` remain available for catalog testing.
diff --git a/doc/how_to_build_macosx_ja.md b/doc/how_to_build_macosx_ja.md
index dbb1b3b51..b493467b2 100644
--- a/doc/how_to_build_macosx_ja.md
+++ b/doc/how_to_build_macosx_ja.md
@@ -89,4 +89,11 @@ $ sudo chmod -R 777 /Applications/OpenToonz
$ open ./toonz/OpenToonz.app
```
-- Xcode でビルドしている場合、アプリケーションは `.toonz/build/Debug/OpenToonz.app` にあります。
\ No newline at end of file
+- Xcode でビルドしている場合、アプリケーションは `.toonz/build/Debug/OpenToonz.app` にあります。
+## Translation workflow / 翻訳
+
+See [Contributing and maintaining translations](../toonz/sources/translations/README.md)
+for contributor and maintainer workflows. Keep the Xcode `WITH_TRANSLATION=OFF`
+workaround above until translation-enabled Xcode builds are verified. That option
+disables this build's translation generation; do not assume bundled catalogs were
+updated. Qt Linguist and manual `lrelease` remain available for catalog testing.
diff --git a/doc/how_to_build_win.md b/doc/how_to_build_win.md
index 842eae0f3..1e6360ebd 100644
--- a/doc/how_to_build_win.md
+++ b/doc/how_to_build_win.md
@@ -200,4 +200,21 @@ OpenToonz utilizes the QuickTime SDK's `mov` and associated file formats. Since
- `$opentoonz/thirdparty/glut/3.7.6/lib/glut32.dll`
## Creating Translation Files
-Qt translation files are generated first from the source code to .ts files, then from .ts files to a .qm file. These files can be created in Visual Studio if the `translation_` project and `Build translation_??? only` (`translation_???`のみをビルド」) is used. These files are not created in the default `Build Project Solution`.
+
+See [Contributing and maintaining translations](../toonz/sources/translations/README.md)
+for contributor submissions and maintainer integration. Qt Linguist editing and
+manual `lrelease` compilation remain supported.
+
+With `WITH_TRANSLATION=ON`, explicitly build a `translate_update_*` project in
+Visual Studio to extract source strings. For example, from the repository root:
+
+```sh
+cmake --build toonz/build --config Release --target translate_update_toonz
+```
+
+Use the configuration and build directory you actually configured. Extraction
+updates source catalogs and can affect all registered languages for the module;
+review the diff before committing. Application targets currently compile `.qm`
+files after linking, but a translation-only edit may not trigger a relink.
+Explicitly release the affected catalogs or confirm their outputs were refreshed.
+The shared guide explains output paths and testing in installed/portable builds.
diff --git a/doc/how_to_build_win_chs.md b/doc/how_to_build_win_chs.md
index 4b2f1005c..76f41472a 100644
--- a/doc/how_to_build_win_chs.md
+++ b/doc/how_to_build_win_chs.md
@@ -198,5 +198,19 @@ OpenToonz 使用 QuickTime SDK 提供的 MOV 及相关文件格式。由于 Quic
- `$opentoonz/thirdparty/glut/3.7.6/lib/glut32.dll`
## 创建翻译文件
-Qt 翻译文件首先使用源码生成.ts文件, 然后使用这些.tx文件生成 .qm 文件。这些文件可以在Visual Studio中创建,只要 `translation_` 项目以及 `Build translation_??? only` (`translation_???`のみをビルド」) 被启用。
-这些文件不会在默认的 `Build Project Solution` 中生成。
\ No newline at end of file
+
+贡献者如何提交翻译,以及维护者如何审核、合并和更新翻译,请参阅
+[翻译指南(英文)](../toonz/sources/translations/README.md)。
+仍可使用 Qt Linguist 编辑 `.ts` 文件并手动运行 `lrelease`。
+
+启用 `WITH_TRANSLATION=ON` 后,在 Visual Studio 中显式构建
+`translate_update_*` 项目可以提取源码中的翻译字符串。例如,从仓库根目录运行:
+
+```sh
+cmake --build toonz/build --config Release --target translate_update_toonz
+```
+
+请使用实际配置的构建目录和配置名称。提取可能更新该模块所有已注册语言的
+`.ts` 文件,提交前应检查差异。当前应用程序目标在链接后生成 `.qm`,
+但只修改翻译可能不会触发重新链接。请手动生成受影响的目录文件,
+或确认输出确实已更新。测试路径和打包说明见上述指南。
diff --git a/doc/how_to_build_win_ja.md b/doc/how_to_build_win_ja.md
index 2d5dfbe69..cc7c303fd 100644
--- a/doc/how_to_build_win_ja.md
+++ b/doc/how_to_build_win_ja.md
@@ -141,4 +141,21 @@ OpenToonz は QuickTime SDK を用いて mov 形式などへ対応していま
- `$opentoonz/thirdparty/glut/3.7.6/lib/glut32.dll`
## 翻訳ファイルの生成
-Qt の翻訳ファイルは、ソースコードから `.ts` ファイルを生成して、 `.ts` ファイルに対して翻訳作業を行い、 `.ts` ファイルから `.qm` ファイルを生成します。Visual Studioソリューション中の`translation_`から始まるプロジェクトに対して「 `translation_???` のみをビルド」を実行すると、 `.ts` ファイルと `.qm` ファイルの生成が行われます。これらのプロジェクトはソリューションのビルドではビルドされないようになっています。
+
+翻訳の提出とメンテナーによる確認・更新については、
+[翻訳ガイド(英語)](../toonz/sources/translations/README.md)を参照してください。
+Qt Linguist での編集と手動の `lrelease` は引き続き利用できます。
+
+`WITH_TRANSLATION=ON` のビルドでは、Visual Studio の `translate_update_*`
+プロジェクトを明示的にビルドすると、ソースから翻訳文字列を抽出できます。
+例(リポジトリのルートから実行):
+
+```sh
+cmake --build toonz/build --config Release --target translate_update_toonz
+```
+
+実際のビルドディレクトリと構成名に置き換えてください。抽出は対象モジュールの
+複数言語の `.ts` を変更するため、コミット前に差分を確認してください。
+現在、アプリケーションのターゲットはリンク後に `.qm` を生成しますが、
+翻訳のみの変更では再リンクされない場合があります。手動でリリースするか、
+生成ファイルが更新されたことを確認してください。
diff --git a/doc/how_to_test_prs.md b/doc/how_to_test_prs.md
index c7ecd968b..2cc95ef47 100644
--- a/doc/how_to_test_prs.md
+++ b/doc/how_to_test_prs.md
@@ -59,3 +59,11 @@ When a PR is submitted, it is compiled automatically by AppVeyor CI. The AppVeyo
- Enter the folder you extracted everything into and double-click the OpenToonz executable to start.
- Test away! Report any suggestions or issues related to the change in the PR comments.
- You can safely delete the .zip file and the folder you created when you are done.
+
+## Testing translation changes
+
+Follow the [translation guide](../toonz/sources/translations/README.md) to check
+which configuration directory the test executable loads. Verify the changed
+`loc/<UI language name>/<module>.qm` is present and current; an executable-only
+update does not establish this. Select the language, restart, and inspect the
+changed UI. Report the language, commit/build, catalog path, and observed wording.
diff --git a/doc/how_to_test_prs_chs.md b/doc/how_to_test_prs_chs.md
index 3040ad149..b1ccb39a4 100644
--- a/doc/how_to_test_prs_chs.md
+++ b/doc/how_to_test_prs_chs.md
@@ -57,3 +57,8 @@
- 进入解压后的文件夹,然后双击`OpenToonz.exe`启动程序。
- 可以开始测试功能。如果有任何建议或者问题,请在PR底下评论。
- 测试完成后可以直接删除压缩包和解压后的文件夹。
+
+## 翻译测试
+
+测试翻译时,请确认实际加载的语言目录和 `.qm` 文件已更新,选择语言后重新启动。
+详细流程参阅[翻译指南(英文)](../toonz/sources/translations/README.md)。
diff --git a/toonz/sources/translations/README.md b/toonz/sources/translations/README.md
new file mode 100644
index 000000000..9c169f572
--- /dev/null
+++ b/toonz/sources/translations/README.md
@@ -0,0 +1,169 @@
+# Contributing and maintaining translations
+
+OpenToonz translations have two kinds of files:
+
+- `.ts` files are editable translation sources, grouped here by language and
+ application module. Contributors normally share these files.
+- `.qm` files are compiled catalogs loaded by OpenToonz. Generate them for
+ testing and packaging; they do not replace the editable sources.
+
+This guide describes the current workflow. Manual Qt Linguist, `lupdate`, and
+`lrelease` workflows remain supported. Planned build-system repairs are not
+required to contribute translations.
+
+## For contributors: share a translation
+
+1. Start with the latest catalog from the branch you intend to contribute to.
+ Use official `master` for contributions to OpenToonz. Find your language directory and the relevant module:
+
+ | Catalog | Typical content |
+ | --- | --- |
+ | `toonz.ts` | Main application, windows, menus, and dialogs |
+ | `tnztools.ts` | Drawing and editing tools |
+ | `toonzqt.ts` | Shared UI widgets and controls |
+ | `toonzlib.ts` | Scene/level infrastructure and related messages |
+ | `tnzcore.ts` | Core infrastructure messages |
+ | `colorfx.ts` | Color styles |
+ | `image.ts` | Image format options and messages |
+
+2. Open the `.ts` file in [Qt Linguist](https://doc.qt.io/qt-5/linguist-translators.html).
+ Edit the translation in its existing context. A repeated English phrase in
+ another context is a separate entry. Mark entries finished only when reviewed.
+ Preserve `%1`, `%2`, `%n`, and other placeholders; retain necessary line breaks
+ and menu mnemonics (`&`, represented as `&amp;` in XML). Use Linguist's
+ validation checks. Do not rename source strings or contexts to translate them.
+
+3. Share the modified `.ts` files through a pull request. Name the language,
+ affected UI, testing performed, and any terminology that needs review. Keep
+ unrelated catalog reformatting and extraction changes out of the submission.
+ Follow [CONTRIBUTING.md](../../../CONTRIBUTING.md) for repository/base selection.
+
+ If a PR is impractical, attach the updated catalogs to an issue or discussion
+ in the destination repository, using a ZIP if the site rejects `.ts` uploads.
+ Include the original catalog version or commit, language, changed areas, and
+ preferred contributor credit. A maintainer can integrate the files for you.
+
+You do not need to compile OpenToonz to contribute wording. Qt Linguist's Release
+action or `lrelease` can optionally generate a `.qm` for local testing. Submit
+editable `.ts` sources; provide generated binaries only when a maintainer asks.
+
+For a new language, ask maintainers to coordinate catalog creation, locale
+metadata, release registration, and review. Adding a directory alone does not
+enable a language in distributed builds.
+
+## For maintainers: review and merge contributed wording
+
+1. Confirm the destination branch and source catalog version. Compare attached
+ files with the current sources instead of overwriting intervening work.
+ Preserve the translator's attribution and any existing co-author credits.
+2. Review the changed contexts, source strings, locale metadata, placeholders,
+ mnemonics, and finished/unfinished status. Seek native-speaker review where
+ needed. Avoid treating XML validity as proof of correct wording.
+3. Compile the affected catalogs with the project's Qt 5 tools. For example,
+ from the repository root, after creating a scratch output directory:
+
+ ```sh
+ lrelease toonz/sources/translations/spanish/toonz.ts -qm /PATH/TO/TEST/toonz.qm
+ ```
+
+ Replace the paths and module with the files under review. On Windows, use a
+ Qt command prompt or invoke the full path to `lrelease.exe`. Review its
+ diagnostics and exit status; an invalid catalog must not be packaged.
+4. Merge the reviewed `.ts` changes through the repository's normal PR process.
+ Regenerate and package the affected `.qm` files, then test that the application
+ loads the new wording. Record the language, build, and checks performed.
+
+## For maintainers: update catalogs when application strings change
+
+Extraction is a maintenance action: `lupdate` scans source and adds/updates `.ts`
+entries. It does not translate new messages. Review its diff before committing;
+new entries may remain unfinished for translators to complete. Keep extraction
+updates separate from unrelated wording changes where practical.
+
+### Existing CMake / Visual Studio targets
+
+Configure an application build with `WITH_TRANSLATION=ON` and the project's Qt 5
+Linguist tools available. From the repository root, an example is:
+
+```sh
+cmake --build toonz/build --config Release --target translate_update_toonz
+```
+
+Use your actual build directory and configured build configuration. Other
+module targets are `translate_update_tnztools`, `translate_update_toonzqt`,
+`translate_update_toonzlib`, `translate_update_tnzcore`,
+`translate_update_colorfx`, and `translate_update_image`. In Visual Studio,
+build the corresponding `translate_update_*` project explicitly. These targets
+can update all registered languages for that module, not just one language.
+The current Qt/CMake update path also generates intermediate `.qm` outputs.
+
+### Existing single-language shell script
+
+With Bash and the intended Qt 5 `lupdate` on PATH, run from the repository root:
+
+```sh
+bash toonz/sources/translations/update.sh spanish
+```
+
+Use the source-directory name, such as `portuguese_brazil`, not the UI display
+name. Always supply the language argument and check that the directory is the
+one intended. The current script has limited argument/error checking and scans
+module directories differently from CMake's source lists. Review every command's
+output and the resulting diff; do not use its final exit status alone as proof
+that every module updated successfully. Creating a new language through this
+script still requires maintainer registration and locale checks.
+
+Direct `lupdate` use remains available for experienced maintainers. Include the
+correct source/header scope and translation context for the module. Do not
+blindly run extraction over the entire repository or third-party libraries.
+
+## Compile, package, and test the resulting catalogs
+
+Current translation-enabled application targets run `lrelease` after linking.
+A `.ts`-only edit may not relink the target, so an otherwise successful no-op
+build is not proof that its `.qm` was refreshed. Until the dependency repair
+lands, compile the affected catalogs explicitly with Linguist or `lrelease`,
+or confirm a target rebuild generated the expected outputs.
+
+The runtime location is the active OpenToonz configuration directory's
+`loc/<UI language name>/<module>.qm`. For a conventional `toonz/build` tree,
+application build rules write into repository `stuff/config/loc`. Source and
+runtime directory names differ:
+
+| Source directory | Runtime language directory |
+| --- | --- |
+| `japanese` | `日本語` |
+| `italian` | `Italiano` |
+| `french` | `Français` |
+| `spanish` | `Español` |
+| `chinese` | `中文` |
+| `german` | `Deutsch` |
+| `russian` | `Русский` |
+| `korean` | `한국어` |
+| `czech` | `Čeština` |
+| `portuguese_brazil` | `Portuguese` |
+
+Norwegian Bokmål sources are present but are not in the current release language
+list. English uses source text rather than a separate English catalog.
+
+Package the generated catalogs from the expected output location. For local
+testing, back up the affected `.qm` before replacing it in the test build's
+active configuration. An installed build and a portable build can use different
+`stuff` directories; verify which one the executable actually loads. Select the
+UI language, restart OpenToonz, and inspect the specific changed controls.
+Check that filenames, saved data, and placeholders remain correct.
+
+If wording stays in English, check the selected language, active configuration
+path, module filename, catalog timestamp, exact source/context match, and
+unfinished status. Qt-owned widget wording and native OS dialogs use separate
+translation mechanisms and may behave differently from OpenToonz catalogs.
+
+## Build-system repair boundary
+
+The intended repair will separate explicit extraction from dependency-tracked
+compilation, so normal builds consume committed `.ts` files without rewriting
+them and translation-only changes regenerate `.qm` files reliably. Existing
+manual workflows should remain usable. Update the build instructions here when
+that behavior has been implemented and verified, rather than assuming it exists
+today. The documented Xcode `WITH_TRANSLATION=OFF` workaround remains applicable
+until translation-enabled Xcode builds are verified.