mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-24 17:32:15 +00:00
[ADF-2463] Moved user guide pages to a subfolder (#3083)
* [ADF-2463] Moved user guide to a subfolder * [ADF-2463] Fixed broken links and images
This commit is contained in:
Andy Stark
committed by
Eugenio Romano
Eugenio Romano
parent
6490260c5d
commit
126e73f5f3
220
docs/user-guide/internationalization.md
Normal file
220
docs/user-guide/internationalization.md
Normal file
@@ -0,0 +1,220 @@
|
||||
---
|
||||
Added: v2.2.0
|
||||
---
|
||||
# Internationalization in ADF
|
||||
|
||||
Internationalization (abbreviated to i18n) is the process of providing UI messages
|
||||
and captions in different human languages to make them easier for readers of those
|
||||
languages to understand. ADF provides full support for i18n in apps. The process does
|
||||
require some extra effort in planning and designing the UI but once implemented, it is
|
||||
fairly straightforward to maintain.
|
||||
|
||||
## Contents
|
||||
|
||||
- [I18n concepts](#i18n-concepts)
|
||||
- [ADF support for i18n](#adf-support-for-i18n)
|
||||
- [Using the translate pipe](#using-the-translate-pipe)
|
||||
- [Adding your own messages](#adding-your-own-messages)
|
||||
- [Interpolations](#interpolations)
|
||||
- [Selecting the display language](#selecting-the-display-language)
|
||||
- [Support for i18n within ADF components](#support-for-i18n-within-adf-components)
|
||||
- [See also](#see-also)
|
||||
|
||||
## I18n concepts
|
||||
|
||||
The main idea behind i18n is to avoid adding natural language text directly into the
|
||||
HTML. Instead, UI messages are represented by short strings known as
|
||||
**keys**. Keys are not displayed directly; they are used to look up the actual text
|
||||
in a list of predefined messages. A typical key/message pair might look like the
|
||||
following:
|
||||
|
||||
"CS_URL_ERROR": "Content Services address doesn't match the URL format"
|
||||
|
||||
Separate lists are kept for each language supported by the app, so for German, the
|
||||
same message would be defined as:
|
||||
|
||||
"CS_URL_ERROR": "Content Services-Adresse nicht im richtigen URL-Format"
|
||||
|
||||
Note that the key is the same in both cases. As long as the UI only ever refers to
|
||||
the keys then changing languages is a simple matter of changing the look-up list.
|
||||
|
||||
## ADF support for i18n
|
||||
|
||||
ADF implements i18n for more than ten languages internally in the display text for
|
||||
components, so you can try out some simple messages without any configuration. The
|
||||
keys are defined in a set of files in the `lib/core/i18n` folder in the ADF sources.
|
||||
|
||||
The files are named according to standard
|
||||
[two-letter language codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes),
|
||||
so `en.json` is the look-up list for English, etc. An excerpt from `en.json` is shown
|
||||
below:
|
||||
|
||||
```json
|
||||
{
|
||||
"FORM": {
|
||||
"START_FORM": {
|
||||
"TITLE": "Start Form"
|
||||
},
|
||||
"PREVIEW": {
|
||||
"IMAGE_NOT_AVAILABLE": "Preview not available"
|
||||
},
|
||||
"FIELD": {
|
||||
"LOCALSTORAGE" : "Local storage",
|
||||
"SOURCE": "Select source from ",
|
||||
"UPLOAD": "UPLOAD",
|
||||
"REQUIRED": "*Required",
|
||||
...
|
||||
```
|
||||
|
||||
The hierarchical structure is referred to in the UI using the familiar "dot"
|
||||
notation (so `FORM.START_FORM.TITLE` would be the key for the "Start Form"
|
||||
string here). This is useful for grouping related messages and providing
|
||||
singular and plural versions, among other things.
|
||||
|
||||
The [Translation service](../core/translation.service.md) defines the `get` method to
|
||||
get the translation of a key in the current language. A simple component might
|
||||
contain code like this:
|
||||
|
||||
```ts
|
||||
import { Component, OnInit } from '@angular/core';
|
||||
|
||||
import { TranslationService } from "@alfresco/adf-core";
|
||||
|
||||
@Component({
|
||||
selector: 'app-home',
|
||||
templateUrl: './home.component.html',
|
||||
styleUrls: ['./home.component.css']
|
||||
})
|
||||
export class HomeComponent implements OnInit {
|
||||
|
||||
constructor(private trans: TranslationService) { }
|
||||
|
||||
translatedText: string = "";
|
||||
|
||||
ngOnInit() {
|
||||
this.trans.get("FORM.START_FORM.TITLE").subscribe(translation => {
|
||||
this.translatedText = translation;
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
...with very simple corresponding HTML:
|
||||
|
||||
```html
|
||||
{{translatedText}}
|
||||
```
|
||||
|
||||
In the browser, this is displayed as:
|
||||
|
||||
|
||||
|
||||
English is used by default but you can easily change the language with the
|
||||
`use` method:
|
||||
|
||||
```ts
|
||||
ngOnInit() {
|
||||
this.trans.use("de");
|
||||
|
||||
this.trans.get("FORM.START_FORM.TITLE").subscribe(translation => {
|
||||
this.translatedText = translation;
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
The user will now see:
|
||||
|
||||
|
||||
|
||||
Note that an unrecognized key will be returned unchanged as the "translation".
|
||||
If you see strings like "FORM.START_FORM.TITLE" displayed in your app then you
|
||||
should check you are using the key correctly.
|
||||
|
||||
## Using the translate pipe
|
||||
|
||||
Using `TranslationService.get` is straightforward but it is often more
|
||||
convenient to add translation keys directly into your page's HTML.
|
||||
Use the `translate` pipe to convert a key in the page directly to the
|
||||
corresponding text. For example, the following will display the
|
||||
"Start Form" text as above but without any code or variables in the
|
||||
component's `.ts` file:
|
||||
|
||||
{{ "FORM.START_FORM.TITLE" | translate }}
|
||||
|
||||
## Adding your own messages
|
||||
|
||||
The built-in translations certainly won't cover everything you will need for
|
||||
your app but you can easily replace them with your own lists. This involves
|
||||
making copies of the existing lists in your app's folder and adding your
|
||||
own keys. See the [Translation service](../core/translation.service.md) page for
|
||||
full details and examples.
|
||||
|
||||
## Interpolations
|
||||
|
||||
Translation messages have support for _interpolation_ (ie, including another
|
||||
string at a specified position within a message). This is very useful for
|
||||
messages whose content can change at runtime. For example, in the built-in
|
||||
`en.json` there is the `CORE.PAGINATION.ITEMS_RANGE` key:
|
||||
|
||||
```json
|
||||
...
|
||||
"CORE": {
|
||||
...
|
||||
"PAGINATION": {
|
||||
"ITEMS_RANGE": "Showing {{ range }} of {{ total }}",
|
||||
"ITEMS_PER_PAGE": "Items per page",
|
||||
...
|
||||
},
|
||||
...
|
||||
```
|
||||
|
||||
The sections in curly braces are _interpolation variables_ that you supply
|
||||
at runtime. You can specify them by passing an extra parameter to
|
||||
`TranslationService.get`; this is an object whose properties have the same
|
||||
names as the interpolation variables in the string:
|
||||
|
||||
```ts
|
||||
this.trans.get(
|
||||
"CORE.PAGINATION.ITEMS_RANGE",
|
||||
{
|
||||
range: "1..10",
|
||||
total: "122"
|
||||
}
|
||||
).subscribe(translation => {
|
||||
this.translatedText = translation;
|
||||
});
|
||||
```
|
||||
|
||||
You can use interpolations with the `translate` pipe in a similar way:
|
||||
|
||||
{{ "CORE.PAGINATION.ITEMS_RANGE" | translate: { range: "1..10", total: "122"} }}
|
||||
|
||||
## Selecting the display language
|
||||
|
||||
ADF provides a [Language Menu component](../core/language-menu.component.md) that
|
||||
you can add to a page to let the user choose their preferred language. The
|
||||
available languages are defined in the `app.config.json` file for the app.
|
||||
|
||||
Note that when the user selects an item from the menu, it simply changes the "locale"
|
||||
preference (which you can get via the [User Preferences service](../core/user-preferences.service.md)).
|
||||
The `translate` pipe reacts automatically to this and changes the page text
|
||||
immediately to the new language. However, text added via a variable set using
|
||||
`TranslationService.get`, as in the example above, will not be updated like this;
|
||||
you will need to get a new translation and set the variable's value again explicitly
|
||||
from the code.
|
||||
|
||||
See the [Language Menu component](../core/language-menu.component.md) page for further
|
||||
details and usage examples.
|
||||
|
||||
## Support for i18n within ADF components
|
||||
|
||||
Some components allow you to use translation keys in places where you would normally
|
||||
supply your own messages directly. For example, the
|
||||
[Data Column component](../core/data-column.component.md) can accept a key instead of
|
||||
normal text to specify the column title. Consult the documentation for a
|
||||
component to see if it has built-in support for i18n.
|
||||
|
||||
## See also
|
||||
|
||||
- [Translation service](../core/translation.service.md)
|
||||
- [Language Menu component](../core/language-menu.component.md)
|
||||
Reference in New Issue
Block a user