Changeset View
Changeset View
Standalone View
Standalone View
src/docs/contributor/internationalization.diviner
@title Internationalization | @title Internationalization | ||||
@group developer | @group developer | ||||
Describes Phabricator translation and localization. | Describes Phorge translation and localization. | ||||
Overview | Overview | ||||
======== | ======== | ||||
Phabricator partially supports internationalization, but many of the tools | Phorge partially supports internationalization, but many of the tools | ||||
are missing or in a prototype state. | are missing or in a prototype state. | ||||
This document describes what tools exist today, how to add new translations, | This document describes what tools exist today, how to add new translations, | ||||
and how to use the translation tools to make a codebase translatable. | and how to use the translation tools to make a codebase translatable. | ||||
Adding a New Locale | Adding a New Locale | ||||
=================== | =================== | ||||
To add a new locale, subclass @{class:PhutilLocale}. This allows you to | To add a new locale, subclass @{class:PhutilLocale}. This allows you to | ||||
introduce a new locale, like "German" or "Klingon". | introduce a new locale, like "German" or "Klingon". | ||||
Once you've created a locale, applications can add translations for that | Once you've created a locale, applications can add translations for that | ||||
locale. | locale. | ||||
For instructions on adding new classes, see | For instructions on adding new classes, see | ||||
@{article@phabcontrib:Adding New Classes}. | @{article@contrib:Adding New Classes}. | ||||
Adding Translations to Locale | Adding Translations to Locale | ||||
============================= | ============================= | ||||
To translate strings, subclass @{class:PhutilTranslation}. Translations need | To translate strings, subclass @{class:PhutilTranslation}. Translations need | ||||
to belong to a locale: the locale defines an available language, and each | to belong to a locale: the locale defines an available language, and each | ||||
translation subclass provides strings for it. | translation subclass provides strings for it. | ||||
Translations are separated from locales so that third-party applications can | Translations are separated from locales so that third-party applications can | ||||
provide translations into different locales without needing to define those | provide translations into different locales without needing to define those | ||||
locales themselves. | locales themselves. | ||||
For instructions on adding new classes, see | For instructions on adding new classes, see | ||||
@{article@phabcontrib:Adding New Classes}. | @{article@contrib:Adding New Classes}. | ||||
Writing Translatable Code | Writing Translatable Code | ||||
========================= | ========================= | ||||
Strings are marked for translation with @{function@arcanist:pht}. | Strings are marked for translation with @{function@arcanist:pht}. | ||||
The `pht()` function takes a string (and possibly some parameters) and returns | The `pht()` function takes a string (and possibly some parameters) and returns | ||||
the translated version of that string in the current viewer's locale, if a | the translated version of that string in the current viewer's locale, if a | ||||
translation is available. | translation is available. | ||||
If text strings will ultimately be read by humans, they should essentially | If text strings will ultimately be read by humans, they should essentially | ||||
always be wrapped in `pht()`. For example: | always be wrapped in `pht()`. For example: | ||||
```lang=php | ```lang=php | ||||
$dialog->appendParagraph(pht('This is an example.')); | $dialog->appendParagraph(pht('This is an example.')); | ||||
``` | ``` | ||||
This allows the code to return the correct Spanish or German or Russian | This allows the code to return the correct Spanish or German or Russian | ||||
version of the text, if the viewer is using Phabricator in one of those | version of the text, if the viewer is using Phorge in one of those | ||||
languages and a translation is available. | languages and a translation is available. | ||||
Using `pht()` properly so that strings are translatable can be tricky. Briefly, | Using `pht()` properly so that strings are translatable can be tricky. Briefly, | ||||
the major rules are: | the major rules are: | ||||
- Only pass static strings as the first parameter to `pht()`. | - Only pass static strings as the first parameter to `pht()`. | ||||
- Use parameters to create strings containing user names, object names, etc. | - Use parameters to create strings containing user names, object names, etc. | ||||
- Translate full sentences, not sentence fragments. | - Translate full sentences, not sentence fragments. | ||||
▲ Show 20 Lines • Show All 200 Lines • ▼ Show 20 Lines | |||||
write the translation: | write the translation: | ||||
```lang=php | ```lang=php | ||||
return pht('This will take %s hour(s).', new PhutilNumber($count)); | return pht('This will take %s hour(s).', new PhutilNumber($count)); | ||||
``` | ``` | ||||
If you now load the web UI, you'll see "hour(s)" literally in the UI. To fix | If you now load the web UI, you'll see "hour(s)" literally in the UI. To fix | ||||
this so the translation sounds better in English, provide translations for this | this so the translation sounds better in English, provide translations for this | ||||
string in the @{class@phabricator:PhabricatorUSEnglishTranslation} file: | string in the @{class:PhabricatorUSEnglishTranslation} file: | ||||
```lang=php | ```lang=php | ||||
'This will take %s hour(s).' => array( | 'This will take %s hour(s).' => array( | ||||
'This will take an hour.', | 'This will take an hour.', | ||||
'This will take hours.', | 'This will take hours.', | ||||
), | ), | ||||
``` | ``` | ||||
▲ Show 20 Lines • Show All 86 Lines • ▼ Show 20 Lines | |||||
Next Steps | Next Steps | ||||
========== | ========== | ||||
Continue by: | Continue by: | ||||
- adding a new locale or translation file with | - adding a new locale or translation file with | ||||
@{article@phabcontrib:Adding New Classes}. | @{article@contrib:Adding New Classes}. |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0