From 5322f8c4b112925228f246ebf3b146cfb03e77f9 Mon Sep 17 00:00:00 2001 From: Jillian Vogel Date: Thu, 18 Jan 2024 17:30:01 +1030 Subject: [PATCH 1/2] docs: Adds ADR 10. Localization --- docs/decisions/0010_localization.rst | 70 ++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/decisions/0010_localization.rst diff --git a/docs/decisions/0010_localization.rst b/docs/decisions/0010_localization.rst new file mode 100644 index 0000000..675bce8 --- /dev/null +++ b/docs/decisions/0010_localization.rst @@ -0,0 +1,70 @@ +10. Localization of user-facing content +####################################### + +Status +****** + +Accepted + +Context +******* + +.. note:: Terminology + + * A "locale" is a specific language and region. + + E.g., Spanish is spoken in several locales: ``es-ar`` (Argentina), ``es-mx`` (Mexico), ``es-es`` (Spain), etc. + + * Internationalization (i18n) is the process of developing products that can be adapted to different languages and + cultures. + + * Localization (l10n) is the process of adapting a product or content for a specific locale. + + +Open edX is used worldwide. So for Aspects to be a fully-supported part of the Open edX ecosystem, it must at least +support translations for user-facing content, page layout for left-to-right and right-to-left languages. It may also +support localized representations of dates and calendars. + +Superset provides Aspect's user interface, and it supports a subset of locales for translating/displaying the menus and +pages that the application serves. However, Superset does not translate its application or asset data, i.e. the +dashboards and charts shown to users. Superset also has some open issues related to localization (e.g. `issue#25258`_). + +Aspects must maintain and display translated versions of its supported Superset assets. + +Decision +******** + +* Aspects build process will support extracting user-facing content from Superset assets for translation, the production + of translated dashboards and charts, and synchronization of the latest translations to the project. +* Normal Aspects users (non-superusers) will only see the dashboards and charts that match their preferred language as + selected in the LMS. +* Open edX superusers using Aspects will see all translations of all Superset assets, so that they are able +* All Superset users may choose their preferred locale for Superset menus and pages from the "Languages" menu after + logging in; this will not be chosen automatically from their Open edX preferred language. +* Aspects will contribute to Superset's i18n and l10n efforts where possible. + +Consequences +************ + +#. Aspects will configure Superset to run with a set of locales that best matches those locales Open edX supports. +#. Aspects will create translated copies of all user-facing Superset assets (dashboards and charts). +#. Like other Open edX projects, translations for the Aspects project will be maintained in Transifex. +#. Translations will be automatically synchronized using the Transifex Github App as per `OEP-58`_. + +Rejected Alternatives +********************* + +**Translate assets on the fly with javascript** + +Another way to implement translations in the browser is using javascript and a mapping between English words/phrases and +the translated words/phrases (e.g. `simple-translator`_). However, this approach cannot discern the context around how +words/phrases are used, and so providing accurate translations for complex content can be difficult or impossible. This +approach would also slow page load times and would provide a sub-standard user experience. + +References +********** + + +.. _OEP-58: https://docs.openedx.org/projects/openedx-proposals/en/latest/architectural-decisions/oep-0058-arch-translations-management.html +.. _issue#25258: https://github.com/apache/superset/issues/25258 +.. _simple-translator: https://github.com/andreasremdt/simple-translator From df0b52c4bd60a7ed2859582aec5e9e3ab744b079 Mon Sep 17 00:00:00 2001 From: Jillian Vogel Date: Thu, 18 Jan 2024 21:18:34 +1030 Subject: [PATCH 2/2] docs: adds point about locale roles and RBAC --- docs/decisions/0010_localization.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/decisions/0010_localization.rst b/docs/decisions/0010_localization.rst index 675bce8..55f4a9d 100644 --- a/docs/decisions/0010_localization.rst +++ b/docs/decisions/0010_localization.rst @@ -48,6 +48,9 @@ Consequences #. Aspects will configure Superset to run with a set of locales that best matches those locales Open edX supports. #. Aspects will create translated copies of all user-facing Superset assets (dashboards and charts). +#. Access to these translated dashboards will be gated by role-based access controls (RBAC) using locale-specific roles. + Users are added to the locale-specific role that best matches their preferred language in Open edX, and so are + granted access to the appropriate translated dashboards and charts. #. Like other Open edX projects, translations for the Aspects project will be maintained in Transifex. #. Translations will be automatically synchronized using the Transifex Github App as per `OEP-58`_.