Commit f413f888 authored by webchick's avatar webchick

Issue #2216541 by jhodgdon, Gábor Hojtsy: Fill in topic/@defgroup docs for...

Issue #2216541 by jhodgdon, Gábor Hojtsy: Fill in topic/@defgroup docs for Internationalization overview.
parent 998e6335
......@@ -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 {
......
......@@ -18,6 +18,8 @@
/**
* Provides a service to handler various date related functionality.
*
* @ingroup i18n
*/
class Date {
use StringTranslationTrait;
......
......@@ -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 {
......
......@@ -7,6 +7,11 @@
namespace Drupal\Core\StringTranslation;
/**
* Interface for the translation.manager translation service.
*
* @ingroup i18n
*/
interface TranslationInterface {
/**
......
......@@ -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.
......
......@@ -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
* @}
*/
......
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