This page describes the process for creating and keeping a translation up to date.

Translation Workflow

Updating a translation is a two-step process:

1. Run the create/update script to extract new strings and open the catalog in Qt Linguist. As part of this extraction, lupdate adds source location information.
2. After saving and closing Qt Linguist, run the cleanup script on the .ts file. Cleanup removes obsolete strings and source location information so the catalog is ready for a pull request.

Translation CI enforces this cleanup for every changed catalog. A pull request will fail validation if its .ts file contains obsolete or vanished strings, or any <location> information. Removing the location information before submission avoids the large amount of unrelated line churn that source file changes would otherwise create.

Windows

Qt Dependencies Setup

1. Clone the repository.
2. Download the dependencies pack from https://github.com/duckstation/dependencies. You'll need the deps-windows-x64.7z file. Extract it to dep\prebuilt.
3. Verify you have lupdate.exe in the following path (replace D:\Projects\duckstation with your clone path): D:\Projects\duckstation\dep\prebuilt\windows-x64\bin.

Create a New Translation

1. Clone the repository in the same way as described in the main README (submodules/recursive clone).
2. Run create-update-and-edit-language.bat in src\duckstation-qt\translations and follow the on-screen instructions.
   • You can find a list of language codes at https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes (use the 639-1 code).
   • If your language has different variants for different countries, append a two-letter country code. You can find a list of country codes at https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes (use the 3166-1 Alpha-2 code).
   • The script creates the .ts file, adds the current strings, and opens it in Qt Linguist.
3. Leave the source language as POSIX. Some languages add an unnecessary country code, so also check Edit > Translation File Settings.
4. Translate the catalog, save it, and close Qt Linguist.
5. Drag the new .ts file onto cleanup-translation.bat.
   • When cleanup succeeds, it reports that the file is ready for a pull request and pauses so you can read the result.

Update an Existing Translation

1. Update your Git repository by running git pull. If it reports local changes, preserve any work you need before cleaning or resetting the repository.
2. Drag the .ts file you wish to edit onto create-update-and-edit-language.bat in src\duckstation-qt\translations.
   • The script adds new strings, reports how many were found, and opens the catalog in Qt Linguist.
3. Translate the new strings, save the catalog, and close Qt Linguist.
4. Drag the .ts file onto cleanup-translation.bat before creating your pull request.

Update the English Catalog

Run update-and-edit-english.bat in src\duckstation-qt\translations. The English update script always removes obsolete strings and omits location information, so a separate cleanup pass is not required.

Linux

The Linux scripts use the bundled tools in dep/prebuilt/linux-x64/bin. Run them from src/duckstation-qt/translations.

Create a New Translation

1. Clone the repository in the same way as described in the main README.

2. Change to the translations directory:

   cd src/duckstation-qt/translations
   

3. Run the create/update script and follow the on-screen instructions:

   ./create-update-and-edit-language.sh
   

   • You can find a list of language codes at https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes (use the 639-1 code).
   • If your language has different variants for different countries, append a two-letter country code. You can find a list of country codes at https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes (use the 3166-1 Alpha-2 code).
   • The script creates the .ts file, adds the current strings, and opens it in Qt Linguist.

4. Leave the source language as POSIX. Some languages add an unnecessary country code, so also check Edit > Translation File Settings.

5. Translate the catalog, save it, and close Qt Linguist.

6. Run cleanup, replacing the example filename with your catalog:

   ./cleanup-translation.sh duckstation-qt_LANGUAGE_CODE.ts
   

   When cleanup succeeds, it reports that the file is ready for a pull request.

Update an Existing Translation

1. Update your Git repository by running git pull. If it reports local changes, preserve any work you need before cleaning or resetting the repository.

2. Change to src/duckstation-qt/translations and pass the catalog to the create/update script:

   ./create-update-and-edit-language.sh duckstation-qt_LANGUAGE_CODE.ts
   

   The script adds new strings, reports how many were found, and opens the catalog in Qt Linguist.

3. Translate the new strings, save the catalog, and close Qt Linguist.

4. Clean the catalog before creating your pull request:

   ./cleanup-translation.sh duckstation-qt_LANGUAGE_CODE.ts
   

Update the English Catalog

Run the English helper from src/duckstation-qt/translations:

./update-and-edit-english.sh

The English update script always removes obsolete strings and omits location information, so a separate cleanup pass is not required.

Translating Strings

1. For each form/context on the left, a list of strings will appear in the middle for translation. A mock version of the UI will also be displayed.
2. Go through each string, entering a translation in your target language in the text box below. Mark the string as Completed (check mark) after doing so, so that when new strings are added you can jump directly to them.
3. Run the platform-specific cleanup script after editing.
4. To submit your translation or updates, follow the normal Git process for forking, creating a branch, and creating a pull request.
   • You only want to submit the changes to your language's .ts file, with no other files.
   • If you are unsure how to do this, send your translation (.ts file) directly to Stenzek or a member of the Translators team on Discord, and it will be committed and pushed for you.

Additional Info

• Refer to the Qt reference manual at https://doc.qt.io/qt-5/linguist-translators.html.
• We also have a #translation channel on Discord where questions can be asked and technical terms clarified.