Translation

Doxygen Translation Agent Skill

This document instructs a translation agent on how to keep all Doxygen and Doxywizard translations up to date, improve translation quality, and handle changes to English source strings.

Overview of Translation Mechanisms

Doxygen uses three separate, independent translation mechanisms:

Each mechanism must be maintained independently. A change in the English text of a source file need to be translated to each of the corresponding Target Files.

Mechanism 1 — Translator Classes (src/translator_xx.h)

How it works

• src/translator.h defines the abstract Translator base class with pure virtual methods such as trRelatedFunctions(), trClassHierarchy(), etc.
• src/translator_en.h contains TranslatorEnglish, which is always fully up to date and is the authoritative source for English strings and their inline documentation comments.
• Each supported language has its own src/translator_xx.h file (e.g. translator_de.h for German, translator_fr.h for French) containing a class such as TranslatorGerman that overrides every method.
• src/translator_adapter.h defines adapter classes (TranslatorAdapter_X_Y_Z) that provide English fallback implementations for methods introduced in a given release. A language translator that is not fully up to date inherits from the appropriate adapter instead of directly from Translator.
• src/language.cpp registers all translators and doc/maintainers.txt lists the human maintainer for each language.

Identifying what needs translation

Run the doc/translator.py script from the repository root to get a full report:

python translator.py --doc .

This generates doc/translator_report.txt and doc/language.dox. The report shows:

• Which translators are fully up to date (inherit directly from Translator)
• Which translators are outdated (inherit from an adapter class) and which methods they are missing
• The percentage of implemented methods per language

CRITICAL — DO NOT COMMIT GENERATED FILES: The files generated by doc/translator.py (doc/translator_report.txt, doc/language.dox, doc/mailto.txt) are auto-generated and must never be staged, committed, or included in pull requests under any circumstances. After running doc/translator.py, always run git checkout -- doc/ or git restore doc/ to discard all changes in the doc/ directory before committing. Only src/translator_xx.h (and optionally .ts / config XML files for the other mechanisms) should appear in commits.

Finding new or changed English strings

When commits touch src/translator_en.h:

1. Use git log --follow -p src/translator_en.h to see all changes.
2. New methods added to TranslatorEnglish are pure virtual in Translator; they must be implemented in every language file or the build will fail.
3. New methods are also added to TranslatorAdapter_X_Y_Z in translator_adapter.h as English fallbacks. A language translator can temporarily inherit from the new adapter; eventually it should provide a real translation.
4. Changed method signatures (parameter lists, return types) must be reflected in all language files that override the method.
5. Removed methods mean the corresponding overrides in language files can be deleted.

How to update a language translator

1. Locate the file: src/translator_xx.h
2. Check the base class: If the class inherits from TranslatorAdapter_X_Y_Z, all methods listed in that adapter (and newer adapters) are missing and fall back to English.
3. Add missing methods: Copy the method signature from TranslatorEnglish and provide a translation. Use and copy the inline comments in translator_en.h to understand the context.
4. Change the base class: Once all methods are implemented, change the base class from TranslatorAdapter_X_Y_Z to Translator directly.
5. Update the adapter: If a new adapter class was added to translator_adapter.h for the current release, it must include the English fallback for each new method.

Run the following script from the root of the repo to check for build errors:

bash .github/skills/translation/compile_language.sh

Quality guidelines for translator classes

• Use domain-appropriate software-development terminology, not generic dictionary translations. For example, "class", "namespace", "template", "typedef", "enum" are technical terms often left in their English form or translated according to the established convention in the target language.
• Use correct accents, diacritics, and ligatures for the target language (e.g., German umlauts ä/ö/ü/ß, French accents é/è/ê/ë, etc.). Encode the file as UTF-8.
• Check that plural forms are grammatically correct; many methods have boolean parameters to select singular vs. plural.
• Check that sentences with embedded variable content (parameter substitution via QCString concatenation or format arguments) remain grammatically correct for all cases.
• Some methods vary their output based on config booleans such as OPTIMIZE_OUTPUT_FOR_C, OPTIMIZE_OUTPUT_VHDL, OPTIMIZE_OUTPUT_SLICE. Translate all branches.
• Keep formatting identical to translator_en.h (same indentation, same brace style).
• Add a comment at the top of the file with your name, date, and a brief changelog entry for the update.

Adding a brand-new language

1. Copy src/translator_en.h to src/translator_xx.h.
2. Rename the class from TranslatorEnglish to TranslatorYourLanguage.
3. Change idLanguage() to return the language name in lowercase English (e.g., "portuguese").
4. Change trISOLang() to return the BCP 47 / ISO language tag (e.g., "pt-PT").
5. Change getLanguageString() to return the correct HTML-help language code.
6. Translate all return values.
7. Include the new file in src/language.cpp and add a case entry in setTranslator().
8. Add an entry in doc/maintainers.txt with your name and e-mail.

Mechanism 2 — Doxywizard Qt Translations (addon/doxywizard/i18n/doxywizard_xx.ts)

How it works

Doxywizard uses Qt's internationalization framework. All user-visible strings in the Doxywizard GUI are wrapped with tr() calls in the C++ source. The Qt Linguist tool extracts these strings into .ts (Translation Source) XML files. At build time the .ts files are compiled into binary .qm files and embedded in the application resources.

Supported languages and their files:

Translation file format

Each .ts file is XML with this structure:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE TS>
<TS version="2.1" language="de">
<context>
    <name>MainWindow</name>
    <message>
        <source>Original English text</source>
        <translation>Translated text</translation>
    </message>
    ...
</context>
</TS>

Translation contexts and their source files:

Identifying new or changed GUI strings

When commits touch any of the Doxywizard .cpp or .h source files, check whether new tr("...") calls have been added or existing ones have changed.

A quick way to scan for changes to translatable strings between two commits:

git log commit1..commit2 --follow -p addon/doxywizard | grep '^[+-].*\btr("'

New or changed tr() calls require updates to every .ts file.

Updating a .ts file

Edit the file directly in any text editor or use Qt Linguist:

1. New string: Add a <message> block inside the appropriate <context> with the <source> text matching exactly what the C++ code passes to tr(), and provide a <translation>.
2. Changed source string: Find the existing <message> by its old <source> text, update <source> to the new English text, and update <translation> accordingly.
3. Removed string: Delete the entire <message> block.
4. Unfinished translation: Qt marks untranslated strings with type="unfinished" on the <translation> element. Remove this attribute once the translation is complete.

Quality guidelines for .ts files

• Preserve placeholders: If the source contains %1, %2, … positional markers, they must appear in the translation (order may differ if the target language requires it).
• Escape XML special characters: Use < for <, > for >, & for &, ' for ', " for ".
• Escape HTML tags: Inside .ts files, HTML tags embedded in strings must also be escaped: write <code> instead of <code>.
• GUI terminology: Use the established software localisation conventions for the target language, e.g. the official Qt or KDE glossary for German or French. Menu items, button labels, and dialog titles follow platform conventions.
• Consistent terminology: Use the same translation for the same English term throughout the file and across different .ts files for the same language.
• File encoding: Files must be UTF-8.