Kibana Globalization - Phase 2

docs/development/plugin/development-internationalization.asciidoc

@@ -0,0 +1,187 @@
+[[translating-kibana]]
+Translating Kibana
+------------------
+
+[[background]]
+Background
+~~~~~~~~~
+
+Please see https://github.com/elastic/kibana/issues/6515[kibana#6515]
+for background discussion on the Kibana translation work.
+
+[[prerequisites]]
+Prerequisites
+~~~~~~~~~~~~
+
+Kibana must be installed and operational, see README.md
+
+[[audience]]
+Audience
+~~~~~~~
+
+There are three audiences for this document:
+
+* those that want to contribute language packs to Kibana
+* those that want to enable translations in existing Kibana plugins
+* those that want to create a new Kibana Plugin
+
+[[contributing-language-packs]]
+Contributing Language Packs
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For this example, we will demonstrate translation into Maltese (Language
+code `mt`). Add-on functionality for Kibana is implemented with plug-in modules.
+Refer to
+https://www.elastic.co/guide/en/kibana/current/kibana-plugins.html[Kibana
+Plugins] for more details.
+
+* Fork the `kibana` source, and ensure you have an up to date copy of
+the source.
+* Ensure you have signed the agreement as in CONTRIBUTING.md
+* Choose the right link:[bcp47] language code for your work. In this
+example, we will use the `kibana` plugin for translating and `mt` for
+Maltese. Other examples might be `zh-Hans` for Chinese using Simplified
+characters, or `az-Cyrl` for Azerbaijani using Cyrillic characters. The
+following links can help:
+* https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes[List of ISO
+639-1 codes]
+*
+http://cldr.unicode.org/index/cldr-spec/picking-the-right-language-code[“Picking
+the right language code”]
+* Create a new branch for your work:
++
+git checkout -b translate-mt
+* For each translation scope (see link:#Enabling%20Translations%20on%20Existing%20Plugins[Enabling Translations on Existing Plugins], below), generate a Kibana plugin with name _plugin_-_languagecode_ using the https://github.com/elastic/generator-kibana-plugin[Kibana Plugin Yeoman Generator]:
++
+* Replace the the `es.json` translation file with _languagecode_`.json`:
+`mv src/plugins/kibana-mt/translations/es.json src/plugins/kibana-mt/translations/mt.json`
+* Translate the `mt.json` file in a JSON editor
+* Edit index file (`kibana-mt/index.js`), updating the
+'translations' item in 'uiExports' as per your plugin translation file(s)
+* Copy translations plugin (`kibana-mt/`) to the Kibana plugins (`<kibana_root>/plugins`) directory
+* Start up Kibana and verify the translation works as expected
+* Ensure Kibana tests pass
+* Commit the `kibana-mt` directory and files, and push them to your own
+fork of `kibana`
+* Open a pull request titled `Translation: Maltese (mt)`
+
+[[enabling-ranslations-on-existing-plugins]]
+Enabling Translations on Existing Plugins
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Kibana translates according to plugin scope, so there is a `.json` file
+in `translations` subdirectory for each plugin.
+
+[[enabling-translation-of-an-angular-view]]
+Enabling Translation of an Angular view
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Determine which views share a plugin scope. In this example, `create`
+and `edit` will share scope.
+* If it does not already exist, Create the appropriate `translation`
+directory and the new translation file `en.json` inside it. In the above
+example, it would be: `src/core_plugins/kibana/translations/en.json`
+* If it does not exist add 'translations' item to the 'uiExports' in the plugin creation (`src/core_plugins/kibana/translations/en.json`) as follows:
+-------------------------------------------------------------------------
+uiExports {
+  translations: [ 
+    resolve(__dirname, './translations/en.json')
+  ], ….
+}
+-------------------------------------------------------------------------
+
+* In the view (HTML) file, such as
+`src/core_plugins/kibana/public/management/sections/indices/_create.html`
+Replace English text with translation keys, and copy the English text
+into the `en.json` file appropriately. Note that loose text was put into
+a `<p></p>` tag for translation purposes. Also note the prefix `KIBANA-`
+matching the plugin being translated.
+
+[[before]]
+Before
+++++++
+
+`_create.html`
+
+-----------------------------------------------------------------------------------------------------
+    <h1>Configure an index pattern</h1>
+    In order to use Kibana you must configure at least one index pattern…
+
+    <kbn-info info="This field will be used to filter events with the global time filter"></kbn-info> 
+-----------------------------------------------------------------------------------------------------
+
+[[after]]
+After
++++++
+
+`_create.html`
+
+-------------------------------------------------------------------------------------------
+    <h1 translate="KIBANA-CONFIGURE_INDEX_PATTERN"</h1>
+    <p translate="KIBANA-MUST_CONFIGURE_INDEX_PATTERN"</p>
+
+    <kbn-info info="{{ 'KIBANA-FIELD_FILTER_EVENTS_GLOBAL_TIME' | translate }}"></kbn-info>
+-------------------------------------------------------------------------------------------
+
+* In the view (JS) file, such as
+`src/core_plugins/kibana/public/management/sections/indices/_create.js`
+As above, replace English text with translation keys, and copy the English text
+into the `en.json` file appropriately. Note that some strings may not be user facing
+and do not need to be replaced then. Also note the prefix `KIBANA-` matching the plugin
+being translated.
+
+[[before]]
+Before
+++++++
+
+`_create.js`
+
+--------------------------------------------------------------------------------------------------------------
+    notify.error('Could not locate any indices matching that pattern. Please add the index to Elasticsearch');
+--------------------------------------------------------------------------------------------------------------
+
+[[after]]
+After
++++++
+
+`_create.js`
+
+-------------------------------------------------------------------------------------------
+    notify.error($translate.instant('KIBANA-NO_INDICES_MATCHING_PATTERN'));
+-------------------------------------------------------------------------------------------
+
+`en.json`
+
+-----------------------------------------------------------------------------------------------------------------------------------------
+    {
+       "KIBANA-CONFIGURE_INDEX_PATTERN": "Configure an index pattern",
+       "KIBANA-MUST_CONFIGURE_INDEX_PATTERN": "In order to use Kibana you must…",
+       "KIBANA-FIELD_FILTER_EVENTS_GLOBAL_TIME" : "This field will be used to filter events with the global time filter",
+       "KIBANA-NO_INDICES_MATCHING_PATTERN": "Could not locate any indices matching that pattern. Please add the index to Elasticsearch",
+    }
+-----------------------------------------------------------------------------------------------------------------------------------------
+
+* Refresh the Kibana page and verify the UI looks the same.
+* Refer to Kibana core plugin (`src/core_plugins/kibana/`) for examples.
+
+[[new-plugin-authors]]
+New Plugin Authors
+~~~~~~~~~~~~~~~~~
+
+Add-on functionality for Kibana is implemented with plug-in modules.
+Refer to
+https://www.elastic.co/guide/en/kibana/current/kibana-plugins.html[Kibana
+Plugins] for more details. It is recommended that when creating a plugin
+you enable translations (see link:#Enabling%20Translations%20on%20Existing%20Plugins[Enabling Translations on Existing Plugins], above).
+
+[[enabling-translation-in-a-plugin]]
+Enabling Translation in a New Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Generate a Kibana plugin using the https://github.com/elastic/generator-kibana-plugin[Kibana Plugin Yeoman Generator]. In this
+example, `plugin1`
+* Add the translation IDs to the views
+* Add the corresponding translation IDs and text to the default translation file (`translations/en.json`)
+* Refer to link:#Enabling%20Translations%20on%20Existing%20Plugins[Enabling Translations on Existing Plugins] for more
+details on enabling translation in your plugin views and refer to Kibana
+core plugin (`src/core_plugins/kibana/`) for an example.

package.json

@@ -89,6 +89,7 @@
     "angular-route": "1.4.7",
     "angular-sanitize": "1.5.7",
     "angular-sortable-view": "0.0.15",
+    "angular-translate": "2.13.1",
     "ansicolors": "0.3.2",
     "autoprefixer": "6.5.4",
     "autoprefixer-loader": "2.0.0",
@@ -215,6 +216,7 @@
     "expect.js": "0.3.1",
     "faker": "1.1.0",
     "grunt": "1.0.1",
+    "grunt-angular-translate": "0.3.0",
     "grunt-aws-s3": "0.14.5",
     "grunt-babel": "6.0.0",
     "grunt-cli": "0.1.13",