Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
development:architecture:localization [2019/06/19 12:46] – [Text Domains] demiankatz | development:architecture:localization [2021/11/09 11:34] – demiankatz |
---|
===== Translate Function ===== | ===== Translate Function ===== |
| |
VuFind uses Zend Framework's translation mechanism. The translator object is registered in the service manager as 'VuFind\Translator'. | VuFind uses Laminas' translation mechanism. The translator object is registered in the service manager under the standard 'Laminas\Mvc\I18n\Translator' key. |
| |
Notes: | Notes: |
* If you attempt to translate a string that is not found in a language map, the original string will be displayed untranslated. | * If you attempt to translate a string that is not found in a language map, the original string will be displayed untranslated. |
* Many of the translated strings in the language files are simply chunks of English text. However, more recent additions are represented as shorter tokens (i.e. "adv_search_filters"). The token approach is often preferable since it allows for more concise map files and reduces the chances of conflicts where the same text has multiple meanings. | * Many of the translated strings in the language files are simply chunks of English text. However, more recent additions are represented as shorter tokens (i.e. "adv_search_filters"). The token approach is often preferable since it allows for more concise map files and reduces the chances of conflicts where the same text has multiple meanings. |
* Starting with VuFind 2.4, a convenient [[https://github.com/vufind-org/vufind/blob/master/module/VuFind/src/VuFind/I18n/Translator/TranslatorAwareTrait.php|TranslatorAwareTrait]] has been added which adds VuFind's standard translation capabilities to any object. Use it in combination with the [[https://github.com/vufind-org/vufind/blob/master/module/VuFind/src/VuFind/I18n/Translator/TranslatorAwareInterface.php|TranslatorAwareInterface]] to have the translator object automatically injected. | * Starting with VuFind 2.4, a convenient [[https://github.com/vufind-org/vufind/blob/dev/module/VuFind/src/VuFind/I18n/Translator/TranslatorAwareTrait.php|TranslatorAwareTrait]] has been added which adds VuFind's standard translation capabilities to any object. Use it in combination with the [[https://github.com/vufind-org/vufind/blob/dev/module/VuFind/src/VuFind/I18n/Translator/TranslatorAwareInterface.php|TranslatorAwareInterface]] to have the translator object automatically injected. |
| |
==== Formatting Language Files ==== | ==== Formatting Language Files ==== |
* Put double-quotes around multi-word phrases on the right side of the equals sign. Do NOT put quotes around phrases on the left side of the equals sign. | * Put double-quotes around multi-word phrases on the right side of the equals sign. Do NOT put quotes around phrases on the left side of the equals sign. |
| |
For an example of a full language file, see [[https://github.com/vufind-org/vufind/blob/master/languages/en.ini|en.ini]]. | For an example of a full language file, see [[https://github.com/vufind-org/vufind/blob/dev/languages/en.ini|en.ini]]. |
| |
:!: Note: If modifications to a language file do not take effect, sometimes it is necessary to clear out the local directory language cache by removing the local/cache/languages directory. The directory should be recreated automatically. | :!: Note: If modifications to a language file do not take effect, sometimes it is necessary to clear out the local directory language cache by removing the local/cache/languages directory. The directory should be recreated automatically. |
==== Adding a New Language ==== | ==== Adding a New Language ==== |
| |
- Create a new language file as described [[#formatting language files|above]] and put it in the languages directory (either in the root of VuFind if you are planning to commit the new language to the master branch, or inside your [[configuration:local_settings_directory|local settings directory]] if this is a local customization). | - Create a new language file as described [[#formatting language files|above]] and put it in the languages directory (either in the root of VuFind if you are planning to commit the new language to the dev branch, or inside your [[configuration:local_settings_directory|local settings directory]] if this is a local customization). |
- If you also wish to translate strings inside text domains (see below) you will need to create appropriate subdirectories inside languages, and put additional language files inside these directories. | - If you also wish to translate strings inside text domains (see below) you will need to create appropriate subdirectories inside languages, and put additional language files inside these directories. |
- If desired, translate help screens as described [[#help screen translation|above]]. | - If desired, translate help screens as described [[#help screen translation|above]]. |
==== Customizing Language Files ==== | ==== Customizing Language Files ==== |
| |
If you need to customize the language files residing in VUFIND_HOME/languages but do not want to commit this customization to the master branch, you only need to create a languages folder in your local folder (or any folder that is configured as your VUFIND_LOCAL_DIR). Any language file in your VUFIND_LOCAL_DIR/languages folder will be merged with its corresponding language file in VUFIND_HOME/languages (implicit inheritance). | If you need to customize the language files residing in VUFIND_HOME/languages but do not want to commit this customization to the dev branch, you only need to create a languages folder in your local folder (or any folder that is configured as your VUFIND_LOCAL_DIR). Any language file in your VUFIND_LOCAL_DIR/languages folder will be merged with its corresponding language file in VUFIND_HOME/languages (implicit inheritance). |
| |
Starting with VuFind 2.5, you can also put a languages directory inside a [[development:architecture:user_interface|theme]] folder to apply custom translations to that specific theme. This can be useful, for example, to use shorter strings in a mobile interface than a desktop version. | Starting with VuFind 2.5, you can also put a languages directory inside a [[development:architecture:user_interface|theme]] folder to apply custom translations to that specific theme. This can be useful, for example, to use shorter strings in a mobile interface than a desktop version. |
| |
$translator->translate('MyDomain::myString'); | $translator->translate('MyDomain::myString'); |
| |
| or |
| |
| $translator->translate(['MyDomain', 'myString']); |
| |
on a valid $translator object would return "The translation". | on a valid $translator object would return "The translation". |
VuFind's help screens contain too much text for the standard translation mechanism to be a practical way of presenting them in multiple languages. Instead, under the theme/root/templates/HelpTranslations directory, the help templates are in folders whose names correspond with VuFind language codes (i.e. "en" for English). When a user requests a help screen, VuFind attempts to serve them the most appropriate version for their selected language, though it defaults to the English version if nothing else is available; as of this writing, help screens have not been translated into all possible languages. | VuFind's help screens contain too much text for the standard translation mechanism to be a practical way of presenting them in multiple languages. Instead, under the theme/root/templates/HelpTranslations directory, the help templates are in folders whose names correspond with VuFind language codes (i.e. "en" for English). When a user requests a help screen, VuFind attempts to serve them the most appropriate version for their selected language, though it defaults to the English version if nothing else is available; as of this writing, help screens have not been translated into all possible languages. |
| |
| ===== Video ===== |
| |
| This topic is discussed in the [[videos:i18n|Internationalization]] video. |
---- struct data ---- | ---- struct data ---- |
---- | ---- |
| |