From 3aa5938daaefc30e21bdd18d1ce2263923cfe12a Mon Sep 17 00:00:00 2001 From: Martin Hickey Date: Mon, 20 Mar 2017 18:09:06 +0000 Subject: [PATCH] Kibana Globalization - Phase 2 (#8766) * Integrate angular-translate globalization framework with i18n engine * Provide template for enabling translations in an AngularJS view by translating a view * Verification tool for translation keys used in angular-translate * Documentation --- .../development-internationalization.asciidoc | 187 ++++++++++++++++++ package.json | 2 + .../management/sections/indices/_create.html | 96 ++++----- .../management/sections/indices/_create.js | 18 +- .../management/sections/indices/index.html | 10 +- src/core_plugins/kibana/translations/en.json | 54 ++++- src/ui/index.js | 2 + src/ui/public/chrome/api/translations.js | 15 ++ src/ui/public/chrome/chrome.js | 2 + src/ui/public/debounce/__tests__/debounce.js | 3 + src/ui/ui_i18n.js | 4 +- tasks/build/verify_translations.js | 39 +++- tasks/config/i18nextract.js | 9 + tasks/utils/i18n_verify_keys.js | 11 +- webpackShims/angular.js | 3 +- webpackShims/ui-bootstrap.js | 10 +- 16 files changed, 380 insertions(+), 85 deletions(-) create mode 100644 docs/development/plugin/development-internationalization.asciidoc create mode 100644 src/ui/public/chrome/api/translations.js create mode 100644 tasks/config/i18nextract.js diff --git a/docs/development/plugin/development-internationalization.asciidoc b/docs/development/plugin/development-internationalization.asciidoc new file mode 100644 index 0000000000000..2550187828838 --- /dev/null +++ b/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 (`/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 `

` tag for translation purposes. Also note the prefix `KIBANA-` +matching the plugin being translated. + +[[before]] +Before +++++++ + +`_create.html` + +----------------------------------------------------------------------------------------------------- +

Configure an index pattern

+ In order to use Kibana you must configure at least one index pattern… + + +----------------------------------------------------------------------------------------------------- + +[[after]] +After ++++++ + +`_create.html` + +------------------------------------------------------------------------------------------- +

+

+ + +------------------------------------------------------------------------------------------- + +* 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. diff --git a/package.json b/package.json index 401a5c8d9b59b..cc319058a07ff 100644 --- a/package.json +++ b/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", @@ -216,6 +217,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", diff --git a/src/core_plugins/kibana/public/management/sections/indices/_create.html b/src/core_plugins/kibana/public/management/sections/indices/_create.html index 9a6aa3a8bb05a..6a63343f8d532 100644 --- a/src/core_plugins/kibana/public/management/sections/indices/_create.html +++ b/src/core_plugins/kibana/public/management/sections/indices/_create.html @@ -2,20 +2,16 @@

-

Configure an index pattern

- In order to use Kibana you must configure at least one index pattern. Index patterns are - used to identify the Elasticsearch index to run search and analytics against. They are also - used to configure fields. +

+

- -

Patterns allow you to define dynamic index names using * as a wildcard. Example: logstash-*

-

Patterns allow you to define dynamic index names. Static text in an index name is denoted using brackets. Example: [logstash-]YYYY.MM.DD. Please note that weeks are setup to use ISO weeks which start on Monday. — - Date Format Documentation

+ +

+

— +

Configure an index pattern

type="text" class="form-control"> - Note: - I noticed you're using weekly indices. Kibana requires ISO weeks be used in your index creation. - See Wikipedia: ISO Week Date +   + + + @@ -38,18 +35,18 @@

Configure an index pattern

- Index contains time-based events +
- Do not expand index pattern when searching (Not recommended) + +
- This index pattern will be queried directly rather than being - expanded into more performant searches against individual indices. + - Elasticsearch will receive a query against {{index.name}} - and will have to search through all matching indices regardless - of whether they have data that matches the current time range. + + +
-

- By default, searches against any time-based index pattern that - contains a wildcard will automatically be expanded to query only - the indices that contain data within the currently selected time - range. -

+

- Searching against the index pattern logstash-* will - actually query elasticsearch for the specific matching indices - (e.g. logstash-2015.12.21) that fall within the current - time range. + + + + +

-

Time-interval based index patterns are deprecated!

-

- We strongly recommend using wildcard pattern names instead of - time-interval based index patterns.

+

- Kibana is now smart enough to automatically determine which - indices to search against within the current time range for - wildcard index patterns. This means that wildcard - index patterns now get the same performance optimizations when - searching within a time range as time-interval patterns. + + +