Add i18n doc #1904
Add i18n doc #1904
Conversation
docs/scos/dev/front-end-development/202212.0/oryx/i18n/localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/i18n/localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/i18n/localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/i18n/localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/i18n/localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/i18n/localization.md
Outdated
Show resolved
Hide resolved
|
|
||
| ## Translation resources | ||
|
|
||
| In order to translate text in Oryx, you can provide translation data in a TS module. You can also integrate those in data provided by a 3rd party translation engine. |
There was a problem hiding this comment.
What do you mean by those in this context?
There was a problem hiding this comment.
What about: "You can also load the text from a 3rd party translation engine."
docs/scos/dev/front-end-development/202212.0/oryx/i18n/localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/i18n/localization.md
Outdated
Show resolved
Hide resolved
|
|
||
| ## Resolve translations from translation resources | ||
|
|
||
| The localization of labels is driven by the current language and the translation key. Translations are supposed to be provided as additional lazy loaded resources next to the component implementation, although they can be added as part of the static resources that are loaded in Oryx as well. If the resources are loaded as external resource, they can be provided by an API (e.g. 3rd party service) or by static JSON files. |
There was a problem hiding this comment.
Supposed by whom?
There was a problem hiding this comment.
by me...
What about: "Translations are typically provided as lazy loaded resources next to the component implementation"
Or: "Translations can be lazy loaded as separate resources, but can also be part of the component code."
|
|
||
| The localization of labels is driven by the current language and the translation key. Translations are supposed to be provided as additional lazy loaded resources next to the component implementation, although they can be added as part of the static resources that are loaded in Oryx as well. If the resources are loaded as external resource, they can be provided by an API (e.g. 3rd party service) or by static JSON files. | ||
|
|
||
| Oryx uses the "current" language to "lookup" the available labels. When the language is `en`, the locales for English are being resolved. |
There was a problem hiding this comment.
What do the quotation marks imply?
There was a problem hiding this comment.
dunno. current can refer to different things. I mean the active language that is used in the frontend.
what about: "Oryx uses the active application language to lookup the available labels."
|
|
||
| If a translation key does not match any of the translations, or if the i18n feature is not installed (which is a default behavior), the translation key is auto-converted to a human readable message. | ||
|
|
||
| For example, if you have a token that contains multiple parts (e.g. `cart.increase`), you can provide a global translation for just the `increase` part or provide a translation for `cart.increase`. This mechanism allows for a single global translation of `increase` that might affect multiple components throughout multiple components. This provides a consistent and convenient translation mechanism, while remaining flexible to add very specific localizations for some components. |
There was a problem hiding this comment.
affect multiple components throughout multiple components Is it possible to avoid the repetition?
There was a problem hiding this comment.
what about: "This mechanism allows for a single translation of increase that might affect multiple components."
ca6c9f6
| }; | ||
| ``` | ||
|
|
||
| The translation engine is based on the standardized [ICU message expressions](https://unicode-org.github.io/icu/userguide/format_parse/messages/). The ICU message format defines a standard syntax to handle common translation cases: |
There was a problem hiding this comment.
Which translation engine are talking about?
docs/scos/dev/front-end-development/202212.0/oryx/i18n/localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/i18n/localization.md
Outdated
Show resolved
Hide resolved
| "order.<count>-items": | ||
| "Products ({count, plural, one {{count} item} other {{count} items}})", | ||
| }; | ||
| {% endraw %}``` |
There was a problem hiding this comment.
not sure if it will be an issue in published docs, maybe not,.but in GitHub markdown preview it breaks rendering (code block is not closed)
There was a problem hiding this comment.
@andriitserkovnyi can you please check? Isn't it because of {% raw %}? But I'm nit really sure.
There was a problem hiding this comment.
I tested the updated version, it will look as expected
|
|
||
| If a translation key doesn't match any of the translations, or if the i18n feature is not installed (which is the default behavior), the translation key is converted into a human-readable message. | ||
|
|
||
| For example, if a token contains multiple parts, like `cart.increase`, you can provide a global translation for just the `increase` part or for `cart.increase`. This mechanism allows for a single translation of `increase` that might affect multiple components. This provides a consistent and convenient translation mechanism while remaining flexible to add specific localizations for some components. |
There was a problem hiding this comment.
This paragraph doesn't fit here, should be in previous point?
There was a problem hiding this comment.
Why? It explains exactly auto-conversion logic, doesn't it?
There was a problem hiding this comment.
for me. it's about providing translations and how translation works, not about auto-conversion of translation tokens?
There was a problem hiding this comment.
Probably you have a point here... I'd it fits both sections, but it's better to put it to the previous one. @andriitserkovnyi can you please move it?
docs/scos/dev/front-end-development/202212.0/oryx/oryx-localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/oryx-localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/oryx-localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/oryx-localization.md
Outdated
Show resolved
Hide resolved
docs/scos/dev/front-end-development/202212.0/oryx/oryx-localization.md
Outdated
Show resolved
Hide resolved
|
|
||
| To support such fine-grained reactivity, a framework specific implementation is required. Oryx provides an `i18n` Lit directive that's used inside components. Using this directive ensures that the DOM is aligned with the localizations in an efficient way. This requires the `@signalAware()` decorator on the component class. To simplify the integration, you can use `I18nMixin` in your component implementation. `I18nMixin` adds `@signalAware()` and exposes the `i18n` function as a method on the component. | ||
|
|
||
| <!-- TODO: add link to signal documentation once it's available so users can read about signals and @signalAware decorator --> |
There was a problem hiding this comment.
Are we going to resolve this TODO after publishing this PR?
docs/scos/dev/front-end-development/202307.0/oryx/oryx-localization.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Vadym Sachenko <vadym.sachenko@spryker.com>
Closes HRZ-2942