Creating or maintaining translations
This page explains the common processes for creating and maintaining Tiki translations, including translations of your own site customizations (_custom).
The basic idea
In PHP files, translatable text is written as tra("here goes the string");.
In Smarty templates (.tpl), use the {tr} block: {tr}Hello world{/tr}.
In JavaScript and Vue files (.js, .vue), use the same tra("...") or tr("...") call (single, double, or backtick-quoted strings all work).
This is how you mark text in Tiki as translatable. Once code is written this way, the translation:getstrings console command scans it and adds any new strings to the language files, untranslated.
Source code: GetStringsCommand.php
Quick start: translating an existing language
This is the most common task: someone wants to continue or improve an existing translation (e.g. French, fr).
1. From the Tiki root, get the latest strings to work from:
php console.php translation:getstrings --lang=fr --skip-remove
This updates lang/fr/language.php with any new English strings. Always add --skip-remove when refreshing an existing translation, without it, any string no longer found by the scan is deleted, including ones you already translated.
2. Edit lang/fr/language.php. Untranslated strings are commented out:
// "Save" => "Save",
3. Uncomment and translate:
"Save" => "Enregistrer",
4. Commit and push.
You can re-run the same command anytime to pick up newly added English strings - your existing translations are always kept, whether or not the string is still found by a fresh scan of the same file.
Creating a brand new language
- Figure out the language code, following RFC 1766:
- Edit lang/langmapping.php to add the new language code and name.
- Create a new directory under lang/ named after the language code, with write permission for the web server.
- Create a starting language.php in that directory - the translation:getstrings command (or the legacy script) updates an existing file. Either:
- copy language.php from a language you're familiar with, or from lang/en/, as a starting point, or
- create an new one yourself.
- Now populate it with every current Tiki string, untranslated:
- Current Tiki (console available):
php console.php translation:getstrings --lang=fr
12. Very old Tiki / SVN checkout: run get_strings.php?lang=fr (change fr to your language code) as admin in the browser. This legacy script collects all the strings from the Tiki code the same way the console command does.
13. Tiki detects the new language automatically once the file exists.
14. Edit/translate lang/fr/language.php as described in the Quick start above.
Don't forget the file must be UTF-8 encoded to display correctly in Tiki.
Translating your site customizations (_custom)
If your site has a _custom/ directory (site-specific code, themes, templates - see _custom), a normal run of translation:getstrings also automatically scans it, plus translatable strings from wiki pages, and writes the result to _custom/shared/lang/<lang>/custom.php. Your core lang/ files are never touched by this pass, and vice versa.
php console.php translation:getstrings --lang=fr --skip-remove // scans core AND _custom/, updates both lang/fr/language.php and _custom/shared/lang/fr/custom.php
To update only the customizations, skipping the core scan entirely:
php console.php translation:getstrings --custom --lang=fr --skip-remove
_custom/shared/lang/<lang>/custom.php must already exist (even as an empty skeleton) before the first run for that language:
<?php $lang_custom = array( ); $lang = array_merge($lang, $lang_custom);
Always use --skip-remove when working with _custom: strings there are frequently hand-added overrides with no matching source file, and without the flag they are silently deleted on every run.
Understanding language.php
Each entry in a language file is either:
- Translated: "Save" => "Enregistrer", - used as-is.
- Untranslated: // "Save" => "Save", - commented out. Uncomment and fill in the translation; remove the // or the next run will overwrite it.
By default, a string no longer found by the scan (its source file changed or was removed) is deleted, translation included. Pass --skip-remove to keep translated strings across runs regardless of whether their source is currently found - only genuinely untranslated placeholders for a removed source are dropped.
Command options
php console.php translation:getstrings [options]
| Option | Effect |
| --lang=xx | Only process language xx (e.g. --lang=fr). Default: all languages found. |
| --skip-remove | Keep strings/translations no longer found by the scan instead of deleting them. |
| --custom | Only scan _custom/ and wiki pages, skipping the core scan. |
| --outputfiles | Add a comment with the file(s) each string was found in. |
| --exclude=dir1,dir2 | Directories excluded from the default scan. |
| --include=file1,file2 | Individual files scanned even inside an excluded directory. |
| --basedir=dir | Legacy: use a single directory as both scan root and language files location. Prefer --custom for _custom/. |
| --filename=name.php | Use a different file name instead of language.php (e.g. language_r.php). |
Maintaining translations between branches
See Translation branching strategy.
Two tools are available to facilitate the merge between trunk and other branches:
- doc/devtools/mergelang.php helps merge translations between branches - see the documentation in the file itself.
- get_strings.php?lang=xx&patch=lang/xx/language.patch where the lang/xx/language.patch is the language.php with new translations