Archive of Kibana i18n Proposal

KibanaProposalArchive.md

archive of the top of

Kibana Globalization Proposal—Introduction

Purpose:

• To perform initial translation-readiness on the Kibana web-facing UI
• IBM team to perform initial Proof-of-Concept (example externalization), and documented best practices/cookbook for externaliation
• Kibana team to perform actual externalization on remainder of codebase

Technology stack

• Node.js, Angular 1.4.7 with bootstrap, d3 rendering library and internal charts

Size

• about 70 HTML views
• about 400+ non-test .js files, ~30k overall LOC

Timeline

Phase 1A

• Related to issue #706
• Scope: Kibana only, not including plugins.
• UI (HTML) content only.
• Proof of Concept test, externalization of "one page"
• UI text: "Select Filter, create dashboard"
• Not including custom Dashboard titles
• Does not include actual translation
• Updated Guidelines
• Translatability (externalization) of remaining views
• translation
  • English .json files in repo
  • Community-provided PRs for translating .json files in core repo (as per #706)
  • Kibana users could "plug in" translation (language) bundles
    • ( This is needed to test the translation )

• Issue #7255 PR #7247

Phase 1AA

• Testing framework
  • automated test to verify translation works - https://github.com/srl295/kibana/commit/cc5b78a434d841e153c6dd8aa73da2ae9272df3e
  • tie-in with lint?
  • issue warning on missing translated constants (new in source, untranslated)
  • issue warning on translated constants which don't have a corresponding key in the source language. (stale translation)

• needs issue filed for Phase 1AA

Phase 1AB

• Improve loading and fallback
  • in Phase 1A, loading is done via GET on individual json files (i.e. en.json for a particular view). Also, fallback mapping is difficult because we don't know which translation files are available
  • Run as an src/optimize phase and generate one bundle (such as i18n-en.bundle.js ) with all of the …/i18n/*.json files per language.
  • extract a language mapping list as well, with a list of installed language bundles [ en, es, … ] so that fallback can be calculated without a lot of 404s
    • perhaps there's already a list of bundles? In any event, it would be great to get this list into one of the other bundles such as kibana.bundle.js.

• needs issue filed for Phase 1AB

Phase 1B

• Issue: elastic/kibana#1171 (discussion)
• Scope: Kibana only, not including plugins.
• "Widget Level" - (i.e. Chart widgets)
• Does not include translating the data itself.
• PoC, externalization of one section of the widget
• Error message
• processing of numbers and dates (time series)
• Evaluate field formatters (#1543) as an approach.
• Not including bidirectional layout
• Updated Guidelines for translatability (externalization) and translation (PRs for translating .json files)

• needs issue filed for Phase 1B

Phase 2

• Enable plug-ability of translations for custom strings like user defined dashboard title
• Might need to allow multiple translated titles per dashboard, per language)
• Updated Guidelines for translatability (externalization) and translation (PRs for translating .json files)

• needs issue filed for Phase 2

Phase 3

• Translation of user data
• Updated Guidelines for translatability (externalization) and translation (PRs for translating .json files)

• needs issue filed for Phase 3

Future/Open Questions

• plugin ecosystem?
• Actual Translation
• The user community in elastic/kibana#706 seems quite interested in pitching in with specific langauge traslations. After PRs for Phase 1A land, request the same users to submit PRs for translated versions of the Kibana English .json files.
• Help system?

Approach

• Angular UI portion:
  • Use angular-translate for simplicity of the UI template resources, taking advantage of angular idioms.
• Non-Angular portion:
  • Source and translations are in basic JSON format, and the same file can be consumed without the angular-translate module. For example, the Node server side can use the JSON format.

BEFORE (HTML)

• field_chooser.html

    <div class="sidebar-list">
    …

    <div class="sidebar-list-header">
        <h5>Selected Fields</h5>
    </div>

AFTER (HTML)

• field_chooser.html

    <div class="sidebar-list">
    …

    <div class="sidebar-list-header">
        <h5 translate="FIELDS_SELECTEDFIELDS"></h5>
    </div>

BEFORE (Chart)

    return new MetricAggType({
      title: 'Count',

AFTER (Chart) - non-Angular

    var uiStrings = …; // loading TBD
    return new MetricAggType({
      title: uiStrings.METRIC_COUNT,

AFTER (JSON)

• kibana-en.json (Example only - specific files to be scoped similar to the .less files.)

    {
        "FIELDS_SELECTEDFIELDS": "Selected Fields",
        "METRIC_COUNT": "Count"
    }

Authors

• Steven R. Loomis, IBM: @srl295
• Scott Russell, IBM: @DTownSMR
• Shikha Srivastava, IBM: @shikhasriva
• Martin Hickey, IBM: @hickeyma