diff --git a/core/lib/Drupal/Core/Annotation/Translation.php b/core/lib/Drupal/Core/Annotation/Translation.php index bb754b6a66e..cb8cff16dcb 100644 --- a/core/lib/Drupal/Core/Annotation/Translation.php +++ b/core/lib/Drupal/Core/Annotation/Translation.php @@ -36,6 +36,8 @@ use Drupal\Core\StringTranslation\TranslationWrapper; * @endcode * Other t() arguments like language code are not valid to pass in. Only * context is supported. + * + * @see i18n * @} */ @@ -47,9 +49,9 @@ use Drupal\Core\StringTranslation\TranslationWrapper; * specified, a context for that string. The string (with optional context) * is passed into t(). * - * @Annotation - * * @ingroup plugin_translatable + * + * @Annotation */ class Translation extends AnnotationBase { diff --git a/core/lib/Drupal/Core/Datetime/Date.php b/core/lib/Drupal/Core/Datetime/Date.php index 2a31eb7b904..aeae7f81344 100644 --- a/core/lib/Drupal/Core/Datetime/Date.php +++ b/core/lib/Drupal/Core/Datetime/Date.php @@ -18,6 +18,8 @@ use Drupal\Core\StringTranslation\StringTranslationTrait; /** * Provides a service to handler various date related functionality. + * + * @ingroup i18n */ class Date { use StringTranslationTrait; diff --git a/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php b/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php index 01e3ec62811..0a9dfc5075c 100644 --- a/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php +++ b/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php @@ -18,6 +18,8 @@ namespace Drupal\Core\StringTranslation; * Procedural code must use the global function t(). Any other approach will * result in untranslatable strings, because the string extractor will not be * able to find them. + * + * @ingroup i18n */ trait StringTranslationTrait { diff --git a/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php b/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php index c3610ff520f..bc560cfd5ee 100644 --- a/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php +++ b/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php @@ -7,6 +7,11 @@ namespace Drupal\Core\StringTranslation; +/** + * Interface for the translation.manager translation service. + * + * @ingroup i18n + */ interface TranslationInterface { /** diff --git a/core/modules/locale/locale.api.php b/core/modules/locale/locale.api.php index 0db2091003b..7dfc6f3fb36 100644 --- a/core/modules/locale/locale.api.php +++ b/core/modules/locale/locale.api.php @@ -8,7 +8,6 @@ /** * @defgroup interface_translation_properties Interface translation properties * @{ - * * .info.yml file properties for interface translation settings. * * For modules hosted on drupal.org, a project definition is automatically added @@ -78,7 +77,8 @@ * - "%version": Project version release. Value examples: "8.1", "8.x-1.0". * - "%language": Language code. Value examples: "fr", "pt-pt". * - * @} End of "defgroup interface_translation_properties". + * @see i18n + * @} */ /** @@ -110,6 +110,7 @@ * Project data as returned by update_get_projects(). * * @see locale_translation_project_list(). + * @ingroup interface_translation_properties */ function hook_locale_translation_projects_alter(&$projects) { // The translations are located at a custom translation sever. diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php index ef0c0a1ce80..e42548dc803 100644 --- a/core/modules/system/core.api.php +++ b/core/modules/system/core.api.php @@ -188,7 +188,8 @@ * 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. + * look there in most Core modules for examples. Note that data types label, + * text, and data_format are translatable; string is non-translatable text. * * @section sec_simple Simple configuration * The simple configuration API should be used for information that will always @@ -261,6 +262,9 @@ * overriding the * \Drupal\Core\Config\Entity\ConfigEntityInterface::calculateDependencies() * method. + * + * @see i18n + * * @} */ @@ -413,6 +417,8 @@ * ->execute(); * $files = $storage->loadMultiple($fids); * @endcode + * + * @see i18n * @} */ @@ -456,12 +462,77 @@ * @{ * Internationalization and translation * - * @todo write this + * The principle of internationalization is that it should be possible to make a + * Drupal site in any language (or a multi-lingual site), where only content in + * the desired language is displayed for any particular page request. In order + * to make this happen, developers of modules, themes, and installation profiles + * need to make sure that all of the displayable content and user interface (UI) + * text that their project deals with is internationalized properly, so that it + * can be translated using the standard Drupal translation mechanisms. * - * Additional documentation paragraphs need to be written, and functions, - * classes, and interfaces need to be added to this topic. + * @section internationalization Internationalization + * Different @link info_types types of information in Drupal @endlink have + * different methods for internationalization, and different portions of the + * UI also have different methods for internationalization. Here is a list of + * the different mechanisms for internationalization, and some notes: + * - UI text is always put into code and related files in English. + * - Any time UI text is displayed using PHP code, it should be passed through + * either the global t() function or a t() method on the class. If it + * involves plurals, it should be passed through either the global + * formatPlural() function or a formatPlural() method on the class. Use + * \Drupal\Core\StringTranslation\StringTranslationTrait to get these methods + * into a class. + * - Dates displayed in the UI should be passed through the 'date' service + * class's format() method. Again see the Services topic; the method to + * call is \Drupal\Core\Datetime\Date::format(). + * - Some YML files contain UI text that is automatically translatable: + * - *.routing.yml files: route titles. This also applies to + * *.local_tasks.yml, *.local_actions, and *.contextual_links.yml files. + * - *.info.yml files: module names and descriptions. + * - For configuration, make sure any configuration that is displayable to + * users is marked as translatable in the configuration schema. Configuration + * types label, text, and date_format are translatable; string is + * non-translatable text. See the @link config_api Config API topic @endlink + * for more information. + * - For annotation, make sure that any text that is displayable in the UI + * is wrapped in \@Translation(). See the + * @link plugin_translatable Plugin translatables topic @endlink for more + * information. + * - Content entities are translatable if they have + * @code + * translatable = TRUE, + * @endcode + * in their annotation. The use of entities to store user-editable content to + * be displayed in the site is highly recommended over creating your own + * method for storing, retrieving, displaying, and internationalizing content. + * - For Twig templates, use 't' or 'trans' filters to indicate translatable + * text. See https://www.drupal.org/node/2133321 for more information. + * - In JavaScript code, use the Drupal.t() and Drupal.formatPlural() functions + * (defined in core/misc/drupal.js) to translate UI text. + * - If you are using a custom module, theme, etc. that is not hosted on + * Drupal.org, see + * @link interface_translation_properties Interface translation properties topic @endlink + * for information on how to make sure your UI text is translatable. * - * See https://drupal.org/node/2133321 and https://drupal.org/node/303984 + * @section translation Translation + * Once your data and user interface are internationalized, the following Core + * modules are used to translate it into different languages (machine names of + * modules in parentheses): + * - Language (language): Define which languages are active on the site. + * - Interface Translation (locale): Translate UI text. + * - Content Translation (content_translation): Translate content entities. + * - Configuration Translation (config_translation): Translate configuration. + * + * The Interface Translation module deserves special mention, because besides + * 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. + * + * @see transliteration * @} */