Commit 1150693b authored by alexpott's avatar alexpott

Issue #2460823 by jhodgdon: Document that locale + config translation...

Issue #2460823 by jhodgdon: Document that locale + config translation integration treats string uniqueness the same way as locale itself
parent cde28ea5
......@@ -236,21 +236,27 @@
* to uninstall/reinstall or use a hook_update_N() function.
* - Exporting and importing configuration.
*
* The file storage format for configuration information in Drupal is @link
* http://en.wikipedia.org/wiki/YAML YAML files. @endlink Configuration is
* The file storage format for configuration information in Drupal is
* @link http://en.wikipedia.org/wiki/YAML YAML files. @endlink Configuration is
* divided into files, each containing one configuration object. The file name
* for a configuration object is equal to the unique name of the configuration,
* with a '.yml' extension. The default configuration files for each module are
* placed in the config/install directory under the top-level module directory,
* so look there in most Core modules for examples.
*
* @section sec_schema Configuration schema and translation
* Each configuration file has a specific structure, which is expressed as a
* YAML-based configuration schema. The configuration schema details the
* structure of the configuration, its data types, and which of its values need
* to be translatable. Each module needs to define its configuration schema in
* files in the config/schema directory under the top-level module directory, so
* look there in most Core modules for examples. Note that data types label,
* text, and data_format are translatable; string is non-translatable text.
* look there in most Core modules for examples.
*
* Configuration can be internationalized; see the
* @link i18n Internationalization topic @endlink for more information. Data
* types label, text, and date_format in configuration schema are translatable;
* string is non-translatable text (the 'translatable' property on a schema
* data type definition indicates that it is translatable).
*
* @section sec_simple Simple configuration
* The simple configuration API should be used for information that will always
......
......@@ -77,12 +77,76 @@
* providing a UI for translating UI text, it also imports community
* translations from the
* @link https://localize.drupal.org Drupal translation server. @endlink If
* UI text in Drupal Core and contributed modules, themes, and installation
* profiles is properly internationalized (as described above), the text is
* automatically added to the translation server for community members to
* translate.
* UI text and provided configuration in Drupal Core and contributed modules,
* themes, and installation profiles is properly internationalized (as described
* above), the text is automatically added to the translation server for
* community members to translate, via *.po files that are generated by
* scanning the project files.
*
* @section context Translation string sharing and context
* By default, translated strings are only translated once, no matter where
* they are being used. For instance, there are many forms with Save
* buttons on them, and they all would have t('Save') in their code. The
* translation system will only store this string once in the translation
* database, so that if the translation is updated, all forms using that text
* will get the updated translation.
*
* Because the source of translation strings is English, and some words in
* English have multiple meanings or uses, this centralized, shared translation
* string storage can sometimes lead to ambiguous translations that are not
* correct for every place the string is used. As an example, the English word
* "May", in a string by itself, could be part of a list of full month names or
* part of a list of 3-letter abbreviated month names. So, in languages where
* the month name for May is longer than 3 letters, you'd need to translate May
* differently depending on how it's being used. To address this problem, the
* translation system includes the concept of the "context" of a translated
* string, which can be used to disambiguate text for translators, and obtain
* the correct translation for each usage of the string.
*
* Here are some examples of how to provide translation context with strings, so
* that this information can be included in *.po files, displayed on the
* localization server for translators, and used to obtain the correct
* translation in the user interface:
* @code
* // PHP code
* t('May', array(), array('context' => 'Long month name');
* format_plural($count, '1 something', '@count somethings',
* array(), array('context' => 'My context'));
*
* // JavaScript code
* Drupal.t('May', {}, {'context': 'Long month name'});
* Drupal.formatPlural(count, '1 something', '@count somethings', {},
* {'context': 'My context'});
*
* // *.links.yml file
* title: 'May'
* title_context: 'Long month name'
*
* // *.routing.yml file
* my.route.name:
* pattern: '/something'
* defaults:
* _title: 'May'
* _title_context: 'Long month name'
*
* // Config schema to say that a certain piece of configuration should be
* // translatable using the Config Translation API. Note that the schema label
* // is also translatable, but it cannot have context.
* date_format:
* type: string
* label: 'PHP date format'
* translatable: true
* translation context: 'PHP date format'
*
* // Twig template
* {% trans with {'context': 'Long month name'} %}
* May
* {% endtrans %}
*
*
* @see transliteration
* @see t()
* @see format_plural()
* @}
*/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment