-
Notifications
You must be signed in to change notification settings - Fork 2
GIP 1 i18n
twelch edited this page Jun 6, 2023
·
1 revision
- SeaSketch Next supports language translation and there is an opportunity for reports to offer language translation in sync (current active language and language switch events).
- Over half of SeaSketch projects would benefit from supporting additional languages in reports, users may want to choose from 2-3 different languages.
Term - A unique string to be translated. Typically it will be the exact string to translate in English language, or it may just be a descriptor.
Overall:
- Should support all languages supported by SeaSketch Next including right-to-left (RTL) languages.
- Both the core geoprocessing library, and individual geoprocessing projects that use it should support translation.
- Geoprocessing projects should be able to build on base translations provided for library UI components, but still be managed independently.
- At runtime, reports will default to english language.
- The SeaSketch platform (via iFrame postMessage) will dictate which language is loaded initially, and be able to change the language.
- If a language is provided that the geoprocessing library or project does not support then it should fallback to English.
Geoprocessing library:
- Core UI components should be 100% translated for all languages.
- The source code will be the source of truth for all terms to be translated, and their English translations, with the exception of specially handled plural terms.
- Terms, and their English translation will mostly be extracted from the source code in an automated process. A manual process may be used for special cases like handling plural terms.
- The geoprocessing library will manage translations for non-english languages for its core UI components and templates using the POEditor platform. POEditor will be the source of truth for these translations.
- Terms/English translations from geoprocessing library code and translated strings from POEditor will be brought together into a single bundle of
base
translations, where they will be mainted in the library git repository.
Geoprocessing projects:
- Geoprocessing projects will install and use the
base
translations from the geoprocessing library for all core UI components and templates used in reports. -
base
terms/translations will be kept separate from project terms/translations in POEditor, as well as in the project. This will ensure that base translations can be upgraded, without affecting project translations. It will also allow project-specific translations to be customized, without losing the base translations. -
base
and project terms/translations should be merged at runtime to provide all of the terms/translations needed for the reports, which will be a mix of core and custom components. If a term exists in both thebase
andproject
translation bundle, the project translation will win. - Geoprocessing projects will manage all other terms and translations for custom reports, using the same workflow as the geoprocessing library.
- Geoprocessing project report developers, who are independent of the SeaSketch team, should be able to manage translations in their own POEditor project, just by changing their access credentials.
- Report developers independent of the SeaSketch team should also have the option to manage translations entirely within the code repo, without using a translation service like POEditor.
- Translators will be invited to the appropriate POEditor project to review and update any and all translations for their language(s) of expertise.
- A single POEditor project will be used to manage both
base
andproject
terms and translations. -
base
terms and translations will be kept separate from project terms and translations in POEditor usingcontext
. Context allows the same term string value to be duplicated in POEditor, with different translations for each.
CLI commands will be the main way developers work with translations.
-
translation:extract
- extracts all translations using babel and babel-plugin-i18next-extract.
-
translation:publish
- Posts translations for all languages to POEDITOR
- Behavior is configured via
src/i18n/config.ts
. Translations with namespace specified bylocalNamespace
are written to POEditor with context value specified byremoteContext
. - All english translations are published, overwriting any in POEditor, since the code is their source of truth.
- For non-english languages, POEditor is the source of truth, so if a translation is not defined in POEditor, then a local project translation is published if available, to seed it the first time.
- For GP projects, if a project translation is not available, then a base translation will be published as fallback if available. Running
translation:import
after that will then import those base translations back and seed the local project translations.
-
translation:import
- fetches translations from POEditor for all non-english languages having context value specified by
remotextContex
property insrc/i18n/config.son
. Any existing translation values will be overwritten. Translations are saved to the namespace specified by thelocalNamespace
property insrc/i18n/config.json
.
- fetches translations from POEditor for all non-english languages having context value specified by
-
translation:sync
- runs in succession
extract
,publish
, thenimport
.
- runs in succession
-
translation:install
(available in gp project only)- copies base translations from the installed geoprocessing library to the projects
src/i18n/baseLang
directory, overwriting any previous version.
- copies base translations from the installed geoprocessing library to the projects
Configuration files:
- A
i18n/supported.ts
file will contain all supported languages, with a unique language code for each. When POEditor is used, then languages get added there as well for each one. - An
i18n/config.json
file will be used to map the local i18n data model (e.g. keys, namespaces) to those of POEditor (terms, context. Specifically it dictates which local i18n namespace to extract translations from (defaults totranslation
), and which remote POEditor context to publish terms/translations to, and import terms/translations from. TheremoteContext
value will vary. For the core geoprocessing library the context will be set tobase
and for geoprocessing project it will be set to the name of the project, as defined in package.json. For example:
geoprocessing library internal config.json:
{
"localNamespace": [
"translation"
],
"remoteContext": [
"base"
]
}
config.json for geoprocessing project called fsm-reports
:
{
"localNamespace": [
"translation"
],
"remoteContext": [
"fsm-reports"
]
}
For geoprocessing library:
- On build of the geoprocessing library, the i18n directory will be copied into the dist folder as part of the base-project.
- CLI commands will live at the root of the monorepo and work on all translatable strings in the
geoprocessing
package, as well as alltemplate-*
packages. - Translations will be maintained in
packages/geoprocessing/src/i18n
- On publish, always push all local English translations. For all non-english langauges, push translations if it doesn't already exist in POEditor.
- Prior to every release of the library, UI text string (terms) will need to get updated in POEditor and translated for all languages.
For geoprocessing projects:
- CLI commands will live at the root of the project.
- When creating a new geoprocessing project, the
base
translations for the current version of the gp library are installed to the project atsrc/i18n/baseLang
. Report developers should not edit this. - Report developers working on a geoprocessing project should not need to make sure that they keep their base translations up to date. They should automatically upgrade on every run of
npm install
using theprepare
command. - Project translations are managed alongside base translations under
src/i18n/lang
. These can be edited but typically will be done via CLI commands (see use cases below). - When initially created, each geoprocessing project will have
base
translations installed. - On publish, always push all local English translations. For all non-english langauges, push translations if it doesn't already exist in POEditor. Additionally, for all languages, if there is no local project translation, fallback to base translation if it exists.
- Prior to a reports being used for planning, UI text strings( terms) will need to get published to POEditor, translated for the relevant subset of languages, then imported back into the library.
-
template-*
monorepo packages are essentially little geoprocessing projects. The only difference is Lerna symlink them to the sibling geoprocessing package onnpm install
. You can treat templates just like a geoprocessing project and use all available CLI commands from within the monorepo. - However, since we chose to converge all i18n translations into the geoprocess packages, if we want translations to load in storybook for templates, you have to symlink the core geoprocessing i18n over to the template. Without that the storybook should still load but the translations will fail in error.
- `ln -s packages/geoprocessing/src/i18n/ packages/template-ocean-eez/src/i18n
- SSN will send a
language
property withinSeasketchReportingInitEvent
message. - It will pass the same code used in SSN.
- geoprocessing library will maintain its own version of that file in its i18n folder, and if SSN sends a code that's not supported it will gracefully fallback to the default language, with a console.warn
- SSN will also send a new message to change language -
SeaSketchReportingChangeLanguageEvent
if the user switches. - App.tsx will read the language code from the postMessage event sent by SSN and store this in context. If there is a change language event, then this code stored in context will be updated. The language will default to
en
English and be updated with the initial language passed by SSN. - A
useLanguage()
hook will be provided that provides access to the current language stored in context and will trigger an update when the language changes. It also offers achangeLanguage()
function, to change the current language. - each project client will load translations by wrapping a
Translator
react component, which creates ani18n
instance (using i18nAsync.ts that lazy loads languages by default but i18nSync.ts is also available) and passes it in toi18nextProvider
. - There is one i18n instance for each report client so that they are isolated and multiple can be loaded in storybook, or even an app at once.
- The Translator will listen for language changes using the useLanguage hook. If it changes, it will tell the i18n instance to change it's language, which will load the appropriate resource file and all translations in the UI will update.
- A language switcher will be wrapped around all stories, allowing the language to be switched.
- Report clients will have a built-in Translator, but for UI components that don't, a Translator is wrapped in the story.
- Translations just work in storybook. Its webpack setup supports dynamic imports.
- As developer creates new reports, they will wrap all strings destined to be displayed in the UI in translate functions using react-i18n such as
t()
,<Trans>
etc. - A
namespace
should not be defined for these strings. - A unique
key
typically does need to be defined for these strings, as the key will default to the english string.
- Developer will configure POEDITOR project ID and Key environment variables.
- Developer will use all translation CLI commands (extract, import, publish, sync)
- Translator will filter by context as needed to just the terms they need to translate.
- The user will create their own POEDITOR project and get the environment variables for project and api key setup.
- If POEditor free account does not suffice, then if you make the report code public and open source, then you can request upgrade to a free premium account in POEditor interface.
- Translator will use POEDITOR to translate, and they will not need to filter by tag because all strings should be reviewed.
- Developer will use
translation:extract
but nottranslation:import
andtranslation:publish
. - Developer uses
i18n-ally
(which vscode settings are established for) to translate strings. - A separate translation service could also be integrated other than POEditor.