Differences

This shows you the differences between two versions of the page.

--- development:architecture:localization [2019/03/07 13:44] – [Formatting Language Files] demiankatz
+++ development:architecture:localization [2024/01/10 13:56] (current) – [Translate Function] demiankatz
@@ Line 1: / Line 1: @@
 ====== Language Support ======
-// This page refers to VuFind 2.x and later; use of earlier versions is no longer recommended. //
 Keywords: localization, l10n, internationalization, i18n
-VuFind supports multiple languages in its user interface through two main mechanisms.
+VuFind® supports multiple languages in its user interface through two main mechanisms.
 ===== 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:
   * 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 abstract keys (i.e. "adv_search_filters").  The abstract key 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.
+  * The translate function can accept an array of values to insert into the translation string in order to include variables inside the translation (e.g. numbers). Placeholders for values are generally surrounded by double-percent-signs (e.g. <nowiki>%%token%%</nowiki>) in the language files. Starting with VuFind® 10.0, an additional argument can be added to the translate function to override the simple search-and-replace value insertion mechanism with the more complex ICU MessageFormatter syntax. When using MessageFormatter syntax, placeholders use braces instead of percent signs. See [[https://github.com/vufind-org/vufind/pull/3286|pull request #3286]] for details and examples.
-==== Formatting Language Files ====
+===== Formatting Language Files =====
 When modifying an existing language file or creating a new one, you should observe these standards:
-  * Save the file in UTF-8 format without a Byte Order Marker (BOM).  Including a BOM may cause VuFind to fail to parse the file correctly.
+  * Save the file in UTF-8 format without a Byte Order Marker (BOM).  Including a BOM may cause VuFind® to fail to parse the file correctly.
-  * Make sure the file is sorted in a case-insensitive manner; VuFind's test suite will complain if language files are out of order, though it will not prevent translations from working properly in the user interface. A command-line tool exists to perform this sorting for you (see below).
+  * Make sure the file is sorted in a case-insensitive manner; VuFind®'s test suite will complain if language files are out of order, though it will not prevent translations from working properly in the user interface. A command-line tool exists to perform this sorting for you (see below).
   * 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.
-=== Sorting Language Files ===
+==== Sorting Language Files ====
 To sort a directory full of language files, simply go to the command line, and from your $VUFIND_HOME directory, run:
@@ Line 35: / Line 34: @@
     php public/index.php language normalize [path_to_language_files]
-VuFind will automatically sort the files for you.
+VuFind® will automatically sort the files for you.
-==== 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 desired, translate help screens as described [[#help screen translation|above]].
   - Edit [[configuration:files:config.ini]] and add your new language to the [Languages] section.
+===== Updating a Language =====
-==== Customizing Language Files ====
+If you wish to maintain an existing set of language files, but you are not sure which strings have been recently added, VuFind® includes a language tool which will generate lists of missing strings in all supported languages. To access it, turn on [[development:troubleshooting#turn_on_development_mode|development mode]] and then add "/DevTools/Language" to the end of your base URL to access the language report.
-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).
+Note also that there are [[administration:command_line_utilities#language_category|language-related command line utilities]] which can help with common maintenance tasks. Most importantly, rather than manually sorting your language files, you can add new/missing strings to the ends, and rely upon the "language normalize" tool to put everything in correct order and format files to project standards.
-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.
+If you want to contribute to the project's translations without modifying code or files, you can also request access to our [[development:architecture:localization:lokalise|Lokalise]] instance.
-=== Defining an Explicit Parent Language File ===
+===== 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 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.
+==== Defining an Explicit Parent Language File ====
 In addition to the above mentioned implicit inheritance of language .ini files VuFind\Il8n\Translator offers a similiar feature as the configuration .ini file's [Parent_Config] section: by adding the line @parent_ini = "relative/path/to/language.ini" to your custom language file in VUFIND_LOCAL_DIR/languages you can reference any other language .ini file as being the parent .ini file.
-== Example 1 ==
+=== Example 1 ===
   * language is set to "de"
@@ Line 64: / Line 69: @@
 The content of vufind2/customlangfiles/custom.ini will be merged into VUFIND_LOCAL_DIR/languages/de.ini and the result is being merged with vufind2/languages/de.ini.
-== Example 2 ==
+=== Example 2 ===
 Using customized language files for a multisite-setup.
@@ Line 102: / Line 107: @@
-==== Text Domains ====
+===== Text Domains =====
-Starting with VuFind 2.5, VuFind supports text domains -- essentially namespaces for language strings. You can create a subdirectory of the languages folder named for the text domain and containing language .ini files named for the appropriate language codes. The text domain is then accessed in the translator by prefixing the string with the text domain and a '::' separator.
+Starting with VuFind® 2.5, VuFind® supports text domains -- essentially namespaces for language strings. You can create a subdirectory of the languages folder named for the text domain and containing language .ini files named for the appropriate language codes. The text domain is then accessed in the translator by prefixing the string with the text domain and a '::' separator.
 For example, suppose you added:
@@ Line 115: / Line 120: @@
     $translator->translate('MyDomain::myString');
+or
+    $translator->translate(['MyDomain', 'myString']);
 on a valid $translator object would return "The translation".
-Text domains currently used by VuFind:
+Text domains currently used by VuFind®:
+  * CallNumberFirst - used for translation of main classification category
   * CreatorRoles - used for translating author relator terms (such as [[https://www.loc.gov/marc/relators/relaterm.html|these]])
   * HoldingStatus - used for displaying complex item availability messages (not supported by all ILS drivers)
+  * Exception - used for exception messages (currently not the exclusive location for these kinds of messages, but refactoring may eventually occur)
 ===== Help Screen 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.
+===== Troubleshooting Language Strings =====
+Starting with VuFind® 9.1, if you activate the "debug" language code in the [Languages] section of config.ini, you can put the software into a mode that will display all of the raw data used in translation, instead of actually applying the translation system. This can be helpful for identifying which strings in the language files need to be overridden to customize particular parts of the interface and for troubleshooting problems.
+===== Related Links =====
+  * [[community:language_support_list|Language Support List]] - a list of volunteers who help with the project's localization (and unclaimed languages which need volunteers).
+===== Video =====
+This topic is discussed in the [[videos:i18n|Internationalization]] video.
 ---- struct data ----
+properties.Page Owner :
 ----