Add built-in translations to components

[jcfranco]

Overview

Currently, our components have placed the responsibility of text translations on the user. Unfortunately, this pattern has lead to some unnecessary boilerplate from teams/projects that have to support more than one locale and do not provide customized strings (e.g., each project needs to set up translation for the same strings and update each component).
The goal for this epic is to make it easier for developers to bring in components w/o having to worry about setting up translations themselves.

Tasks

• Define pattern for localized components (see notes below) (feat: add built-in translations #5065)

  • Deprecate intl<Prop>s as these should no longer be needed Epic: remove deprecated intl properties & accessible label properties. #5946
  • Determine if we need support for overrides at 1.0.0

• Add script to generate types for t9n bundles for type safety (feat: add built-in translations #5065)

• Plan automation of translation-bundles

  • make sure to follow supported locales
  • use t9n naming
  • need to consider that designs may need to be updated to accommodate translations (aim to get translations early for this)
  • keep CLDR data-driven strings (e.g., dates, raw number data) outside of bundles
  • special considerations may be needed for RTL
  • error strings will need to be localized
    action items
  • Franco + Anvesh will work on a PR with the translation bundle scaffolding in place
  • Once ☝️ is ready, the next steps is to review and test our setup

Notes

• No implementation details should be exposed, this will give us total flexibility on translation/loading implementation, we can revisit if we need to adopt a different lib for consistency across components – first iteration can be a simple JSON file fetcher
• String bundles should:
  • be placed under src/components/<component>/assets/t9n/
  • have a main bundle (manually updated), and the rest will be automatically generated and named per their locale
    • the structure for the above could be anything as long as it does not unnecessarily add bytes, is easy to maintain and is clear to distinguish the main file from the rest
  • be JSON files – need to determine structure (a flat object of strings may be the best way to support string overrides, if needed
• To support backwards-compatibility:
  • intl<Prop> values should no longer be set by default
  • after loading the built-in bundle, any provided intl<Prop>s should be merged w/ the built-in strings
  • technically, this would break anyone referencing the strings, but we expect this to not be a common use case
• requests/bundles must be cached to handle multiple components of the same type loading later or in parallel
• All core t9n behavior should be placed in a module and reused across components

Questions

• Do we need to support runtime locale changes before 1.0.0?
  • one idea would be to only support at the HTML level and set up a mutation observer
• Do we need to support changes at a global level (e.g., change strings for all buttons vs per instance) before 1.0.0?
• Where to derive locale from (e.g., navigator.language, document.documentOwner.lang, global util)?
• How often to update locale bundles?

Additional Resources

Prototype: #4960

i18n libs

• https://github.com/i18next/i18next
• https://github.com/i18next/next-i18next
• https://github.com/lisanjs/lisan

cc @benelan @geospatialem

[anveshmekala]

Following is the list of high-risk locales provided by @annierm18 from localization team which can be used to test before shipping PR #5471

• Western languages – German, Spanish, French
• Norwegian
• Asian languages – Japanese, Chinese (Simplified or Traditional)
• RTL/bi-di languages – Arabic, Hebrew
• Cyrillic and non-Latin languages – Russian, Ukrainian, Greek
• Other – Thai, Turkish, any specific customer language

[annierm18]

I have completed testing for the test cases listed in the screen shot below. Tickets were opened for all issues found (links are included in screenshot).

cc: @anveshmekala

[github-actions]

Installed and assigned for verification.

[geospatialem]

Verified on master. Note the path to the string bundles is src/components/<component>/assets/<component>/t9n/, where the full path differs from the proposal above, but is acceptable.

Of the above issues mentioned by Aine above, 2 have been closed and are included in the 1.0 release, and the remaining lower priority issues have been allocated to the February milestone.