From f413f8889466e6ee2581f0344987e6e6eb549574 Mon Sep 17 00:00:00 2001
From: webchick <drupal@webchick.net>
Date: Mon, 23 Jun 2014 09:03:29 -0700
Subject: [PATCH] =?UTF-8?q?Issue=20#2216541=20by=20jhodgdon,=20G=C3=A1bor?=
=?UTF-8?q?=20Hojtsy:=20Fill=20in=20topic/@defgroup=20docs=20for=20Interna?=
=?UTF-8?q?tionalization=20overview.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.../Drupal/Core/Annotation/Translation.php | 6 +-
core/lib/Drupal/Core/Datetime/Date.php | 2 +
.../StringTranslationTrait.php | 2 +
.../TranslationInterface.php | 5 ++
core/modules/locale/locale.api.php | 5 +-
core/modules/system/core.api.php | 83 +++++++++++++++++--
6 files changed, 93 insertions(+), 10 deletions(-)
diff --git a/core/lib/Drupal/Core/Annotation/Translation.php b/core/lib/Drupal/Core/Annotation/Translation.php
index bb754b6a66ea..cb8cff16dcb7 100644
--- a/core/lib/Drupal/Core/Annotation/Translation.php
+++ b/core/lib/Drupal/Core/Annotation/Translation.php
@@ -36,6 +36,8 @@
* @endcode
* Other t() arguments like language code are not valid to pass in. Only
* context is supported.
+ *
+ * @see i18n
* @}
*/
@@ -47,9 +49,9 @@
* 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 2a31eb7b904c..aeae7f81344e 100644
--- a/core/lib/Drupal/Core/Datetime/Date.php
+++ b/core/lib/Drupal/Core/Datetime/Date.php
@@ -18,6 +18,8 @@
/**
* 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 01e3ec628114..0a9dfc5075c0 100644
--- a/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php
+++ b/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php
@@ -18,6 +18,8 @@
* 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 c3610ff520f0..bc560cfd5ee4 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 0db2091003bf..7dfc6f3fb36d 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 ef0c0a1ce80d..e42548dc803f 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
- *
- * Additional documentation paragraphs need to be written, and functions,
- * classes, and interfaces need to be added to this topic.
+ * 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.
+ *
+ * @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.
+ *
+ * @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 https://drupal.org/node/2133321 and https://drupal.org/node/303984
+ * @see transliteration
* @}
*/
--
GitLab