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.mdindex 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.mdindex 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 ThanksThis 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdnew file mode 100644index 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 `&` 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.