diff --git a/TRANSLATION.md b/TRANSLATION.md deleted file mode 100644 index 4720e6c1b3253aa..000000000000000 --- a/TRANSLATION.md +++ /dev/null @@ -1,140 +0,0 @@ -Translating Kibana -=== - -Background ---- - -Please see [kibana#6515](https://github.com/elastic/kibana/issues/6515) -for background discussion on the Kibana translation work. - -Prerequisites ---- - -Kibana must be installed and operational, see README.md - -Audience ---- - -There are three audiences for this document: -- those that want to contribute translations to Kibana -- those that want to enable translation of Kibana -- those that want to create a Kibana Plugin - -Contributing Translations ---- - -For this example, we will demonstrate translation into Maltese (Language code `mt`). - -- 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 [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: - - [List of ISO 639-1 codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) - - [“Picking the right language code”](http://cldr.unicode.org/index/cldr-spec/picking-the-right-language-code) -- Create a new branch for your work: - - git checkout -b translate-mt - -- For each translation scope -(see [Scoping Translations](#Scoping Translations), below), -copy the translation plugin template directory `translation_plugin_template` to `/plugins` changing the directory name to _plugin_-_languagecode_: - - cp -r src/fixtures/translation_plugin_template src/plugins; mv src/plugins/translation_plugin_template src/plugins/kibana-mt - … - -- Replace the the `en.json` English source with _languagecode_`.json`: - mv src/plugins/kibana-mt/translations/en.json src/plugins/kibana-mt/translations/mt.json - -- Translate the `mt.json` file in a JSON editor - -- Edit index file (`src/plugins/kibana-mt/index.js`), updating the 'translations' item as per your plugin translation(s) and changing plugin id to you plugin name (`kibana-mt`) - -- Edit package file (`src/plugins/kibana-mt/package`), updating the 'name' field to your plugin name (`kibana-mt`) - -- See `src/fixtures/translation_plugin_template/README.mt` for more details - -- 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)` - - -Scoping Translations ---- -Kibana translates according to plugin scope, so there is -a `.json` file in `translations` subdirectory -for each plugin. - -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` - -* 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 #### -`_create.html` -``` -

Configure an index pattern

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

KIBANA-H1_CONFIGURE_INDEX_PATTERN

-

KIBANA-MUST_CONFIGURE_INDEX_PATTERN

-``` - -`en.json` -``` - { - "KIBANA-H1_CONFIGURE_INDEX_PATTERN": "Configure an index pattern", - "KIBANA-MUST_CONFIGURE_INDEX_PATTERN": "In order to use Kibana you must…" - } -``` - -* Refresh the Kibana page and verify the UI looks the same. - -* Refer to Kibana core plugin (`src/core_plugins/kibana/`) for examples. - -Plugin Authors ---- - -Add-on functionality for Kibana is implemented with plug-in modules. Refer to [Kibana Plugins](https://www.elastic.co/guide/en/kibana/current/kibana-plugins.html) for more details. It is recommended that when creating a plugin you enable translations (see [Scoping Translations](#Scoping Translations), above). - -Enabling Translation in a Plugin ---- - -* If the plugin does not exist already, create the plugin. -In this example, `plugin1` - -* Create the appropriate `translation` directory and the new translation file `en.json` inside it. -In the above example, it would be: - `src/plugins/plugin1/translations/en.json` - -* A plugin publishes its translation file(s) via `uiExports` by adding the `translations` key and listing the path(s) to the translation file(s) in the plugin creation code (`return new kibana.Plugin`) as follows: -`uiExports: { - translations: [ - resolve(__dirname, './translations/en.json') - ] -}` - -* Refer to [Scoping Translations](#Scoping Translations) 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/docs/development/plugin/development-internationalization.asciidoc b/docs/development/plugin/development-internationalization.asciidoc new file mode 100644 index 000000000000000..512b0889e1e911e --- /dev/null +++ b/docs/development/plugin/development-internationalization.asciidoc @@ -0,0 +1,158 @@ +[[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 translations to Kibana - those that want to enable +translation of Kibana - those that want to create a Kibana Plugin + +[[contributing-translations]] +Contributing Translations +~~~~~~~~~~~~~~~~~~~~~~~~~ + +For this example, we will demonstrate translation into Maltese (Language +code `mt`). + +* 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:#Scoping%20Translations[Scoping +Translations], below), copy the translation plugin template directory +`translation_plugin_template` to `/plugins` changing the +directory name to _plugin_-_languagecode_: ++ +cp -r src/fixtures/translation_plugin_template src/plugins; mv +src/plugins/translation_plugin_template src/plugins/kibana-mt … +* Replace the the `en.json` English source with _languagecode_`.json`: +mv src/plugins/kibana-mt/translations/en.json +src/plugins/kibana-mt/translations/mt.json +* Translate the `mt.json` file in a JSON editor +* Edit index file (`src/plugins/kibana-mt/index.js`), updating the +'translations' item as per your plugin translation(s) and changing +plugin id to you plugin name (`kibana-mt`) +* Edit package file (`src/plugins/kibana-mt/package`), updating the +'name' field to your plugin name (`kibana-mt`) +* See `src/fixtures/translation_plugin_template/README.mt` for more +details +* 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)` + +[[scoping-translations]] +Scoping Translations +~~~~~~~~~~~~~~~~~~~~ + +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` +* 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` + +-------------------------------------------------------- +

KIBANA-H1_CONFIGURE_INDEX_PATTERN

+

KIBANA-MUST_CONFIGURE_INDEX_PATTERN

+-------------------------------------------------------- + +`en.json` + +-------------------------------------------------------------------------------- + { + "KIBANA-H1_CONFIGURE_INDEX_PATTERN": "Configure an index pattern", + "KIBANA-MUST_CONFIGURE_INDEX_PATTERN": "In order to use Kibana you must…" + } +-------------------------------------------------------------------------------- + +* Refresh the Kibana page and verify the UI looks the same. +* Refer to Kibana core plugin (`src/core_plugins/kibana/`) for examples. + +[[plugin-authors]] +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:#Scoping%20Translations[Scoping +Translations], above). + +[[enabling-translation-in-a-plugin]] +Enabling Translation in a Plugin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* If the plugin does not exist already, create the plugin. In this +example, `plugin1` +* Create the appropriate `translation` directory and the new translation +file `en.json` inside it. In the above example, it would be: +`src/plugins/plugin1/translations/en.json` +* A plugin publishes its translation file(s) via `uiExports` by adding +the `translations` key and listing the path(s) to the translation +file(s) in the plugin creation code (`return new kibana.Plugin`) as +follows: +`uiExports: { translations: [ resolve(__dirname, './translations/en.json') ] }` +* Refer to link:#Scoping%20Translations[Scoping Translations] 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/src/fixtures/translation_plugin_template/README.md b/src/fixtures/translation_plugin_template/README.md deleted file mode 100644 index 2929654484ab9b8..000000000000000 --- a/src/fixtures/translation_plugin_template/README.md +++ /dev/null @@ -1,23 +0,0 @@ -A Kibana translation plugin structure. - -The main goal is to keep the plugin extremely simple so non-technical translators will have no trouble -creating new translations for Kibana. Everything except for the translations themselves can be generated -automatically with some enhancements to the Kibana plugin generator. The generator would only need a -plugin name and a list of one or more languages the user wants to create translations for. - -The plugin exports its translation file(s) on the server when it it starts up. This is achieved by publishing the files -via 'uiExports'.This is configurable by modifying the 'translations' item in the 'uiExports'. - -Translation files are broken up by language and must have names that match IETF BCP 47 language codes. -Each translation file contains a single flat object with translation strings matched to their unique keys. Keys are -prefixed with plugin names and a dash to ensure uniqueness between plugins. A translation plugin is not restricted to -providing translations only for itself, the provided translations can cover other plugins as well. - -For example, this template plugin shows how a third party plugin might provide spanish translations for the Kibana core "kibana" app, which is itself a separate plugin. - -To manually create a translation plugin using this template, follow these steps: - 1. Copy this template directory to /plugins, changing the directory name to your plugin name. - 2. Add your translations files to /translations directory. Remove/Overwrite the existing translation file (i.e. 'es.json'). - 3. Edit /index.js, updating the 'translations' item as per your plugin translations. - 4. Edit /package, updating the 'name' field to your plugin name. - 5. Restart the Kibana server to publish your plugin translations. diff --git a/src/fixtures/translation_plugin_template/index.js b/src/fixtures/translation_plugin_template/index.js deleted file mode 100644 index 1e139ee463916d5..000000000000000 --- a/src/fixtures/translation_plugin_template/index.js +++ /dev/null @@ -1,13 +0,0 @@ -import { resolve } from 'path'; - -export default function (kibana) { - return new kibana.Plugin({ - id: 'kibana-es', - - uiExports: { - translations: [ - resolve(__dirname, './translations/es.json') - ] - } - }); -} diff --git a/src/fixtures/translation_plugin_template/package.json b/src/fixtures/translation_plugin_template/package.json deleted file mode 100644 index e747c010ede4eeb..000000000000000 --- a/src/fixtures/translation_plugin_template/package.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "name": "kibana-es", - "version": "kibana" -} diff --git a/src/fixtures/translation_plugin_template/translations/es.json b/src/fixtures/translation_plugin_template/translations/es.json deleted file mode 100644 index 9506d55ab54759f..000000000000000 --- a/src/fixtures/translation_plugin_template/translations/es.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "UI-WELCOME_MESSAGE": "Cargando Kibana", - "UI-WELCOME_ERROR": "Kibana no se cargó correctamente. Heck la salida del servidor para obtener más información." -} diff --git a/src/ui/public/chrome/api/translations.js b/src/ui/public/chrome/api/translations.js index 3d4eec178bfa3fe..6d8455fa84c32d8 100644 --- a/src/ui/public/chrome/api/translations.js +++ b/src/ui/public/chrome/api/translations.js @@ -1,5 +1,15 @@ -export default function (chrome, internals) { +module.exports = function (chrome, internals) { + /** + * ui/chrome Translations API + * + * Translations + * Returns the translations which have been loaded by the Kibana server instance + */ + + /** + * @return {Object} - Translations + */ chrome.getTranslations = function () { return internals.translations || []; }; -} +}; diff --git a/src/ui/public/chrome/chrome.js b/src/ui/public/chrome/chrome.js index cb61585e5ffd2ec..ca3180881733cf7 100644 --- a/src/ui/public/chrome/chrome.js +++ b/src/ui/public/chrome/chrome.js @@ -18,6 +18,7 @@ import controlsApi from './api/controls'; import navApi from './api/nav'; import templateApi from './api/template'; import themeApi from './api/theme'; +import translationsApi from './api/translations'; import xsrfApi from './api/xsrf'; const chrome = {}; @@ -43,7 +44,7 @@ angularApi(chrome, internals); controlsApi(chrome, internals); templateApi(chrome, internals); themeApi(chrome, internals); -require('./api/translations')(chrome, internals); +translationsApi(chrome, internals); chrome.bootstrap = function () { chrome.setupAngular(); diff --git a/webpackShims/angular.js b/webpackShims/angular.js index 6e0bf426380754f..9cc9932944d49f3 100644 --- a/webpackShims/angular.js +++ b/webpackShims/angular.js @@ -1,6 +1,6 @@ require('jquery'); require('node_modules/angular/angular'); -require('node_modules/angular-translate/dist/angular-translate.min'); +require('node_modules/angular-translate'); module.exports = window.angular; require('node_modules/angular-elastic/elastic'); diff --git a/webpackShims/ui-bootstrap.js b/webpackShims/ui-bootstrap.js index eeb082707e94bf7..7ac6127f810ac0c 100644 --- a/webpackShims/ui-bootstrap.js +++ b/webpackShims/ui-bootstrap.js @@ -8,20 +8,12 @@ define(function (require) { .config(function ($tooltipProvider) { $tooltipProvider.setTriggers({ 'mouseenter': 'mouseleave click' }); }) - .factory('translationsLoader', function ($q) { - return function (options) { - var deferred = $q.defer(); - const translations = chrome.getTranslations(); - deferred.resolve(translations); - return deferred.promise; - }; - }) - .config(['$translateProvider', function ($translateProvider) { - $translateProvider.preferredLanguage('en'); - $translateProvider.useLoader('translationsLoader'); + .config(function ($translateProvider) { + $translateProvider.translations('default', chrome.getTranslations()); + $translateProvider.preferredLanguage('default'); // Enable escaping of HTML // issue in https://angular-translate.github.io/docs/#/guide/19_security $translateProvider.useSanitizeValueStrategy('escapeParameters'); - }]); + }); });