For every new translation require an id and value string should be added on an English file at the properties folder. The values on these files will replace the matching id on every .html and .ts file on build time. All the none English .properties files are generated by Transifex and should not be modified manually.
Please note that for every feature module a translation file should exist on the (properties folder)[https://github.com/ORCID/orcid-angular/tree/master/src/locale/properties] with the following name standard:
<kebab-case-feature-name>/<kebab-case-feature-name>.en.properties
For any HTML template that contains text like the following
<button>MORE NEWS</button>
A translation tag should be added using an HTML attribute i18n with a value of `@@
For instance
<button i18n="@@home.more_news">MORE NEWS</button>
Similar to the template, use the id and the value of the translation as following
$localize`:@@home.more_news:MORE NEWS`
Angular is currently unable to extract translations from TS files until TS extractions are implemented on Angular 10. This extraction is required to translate the string on build time.
So is important to add the translations on the component /src/locale/i18n.pseudo.component.html
For instance, add the line:
<var i18n="@@home.more_news">MORE NEWS</var>
Translations are done via Transifex by a combination of ORCID staff, community volunteers and external vendors.
This Github repository is connected to a Transifex via an integration that is configured in Transifex (see Transifex Github integration docs). When changes to files in orcid-angular/src/locale/properties are merged to master, this integration automatically pulls changes into our Transifex orcid-angular project.
To make new properties files available to translators, you need to add the file info to the integration configuration in Transifex:
-
Visit https://www.transifex.com/orcid-inc-1/orcid-angular/settings/integrations/ (you will need a Transifex account with admin access - post in Slack #translations if you need access)
-
In the Github section, click Edit settings
-
In the Select Files section, add a new file filter to the YAML config that includes the path to the new file in Github, ex:
- filter_type: file file_format: UNICODEPROPERTIES source_language: en source_file: src/locale/properties/signin/signin.en.properties # path expression to translation files, must contain <lang> placeholder translation_files_expression: src/locale/properties/signin/signin.<lang>.properties -
Click Update Settings. The sync should start running, and the new file will appear in orcid-angular > Resources
-
Finally add the new file to the local Transifex .tx/config
You can add new strings to properties files in English by:
- add a new property on any of the existing English properties files
- generate the testing languages
To update an existing string change the English text and add the Transifex Project Maintainer to the Trello card for the fix (create a card if there is not one already) so they are aware of this update. Include both the key and value for each changed string on the card.
With new strings added to Orcid Angular properties files, it is possible to clone the translations for the same strings on Orcid Source.
For this, the translation should meet the following conditions
- The property on Orcid Angular doesn't have a translation for a certain language and Orcid Source has it
- The English text of the property on Orcid Angular and Orcid Source are the same
To do this call the following script yarn build:i18n:clone '<orcid-angular local folder>' '<orcid source i18n folder>'
for instance:
yarn build:i18n:clone 'D:/workspace/orcid-angular/src/locale/properties' 'D:/workspace/ORCID-Source/orcid-core/src/main/resources/i18n'
This will create a /temp folder on the root of the project orcid-angular project , with all the translations files, from that the required translations files can be copied and pasted on orcid angular local/properties folder. This should be done carefully since not just because the English version of a string match between Orcid Source and Orcid Angular means that the same translation is correct for all languages.
The LR, RL and XX testing languages are automatically generated when yarn build:i18n:clone is call and by
This will run automatically as a Github action. But can also be manually run npm run build:i18n:generate-testing
Transifex Github integration will keep the .properties sync. This is done by getting change on the .properties English files into Transifex, and when a file gets a 100% translated on Transifex for any language Transifex creates a PR to add the .properties file for that language.
If the automatic push/pull is not enough or fails, files can be transferred manually via the Transifex client or the Transifex API.
- Install the Transifex client
- (Generate your API token)[https://www.transifex.com/user/settings/api/] the CLI will ask for one before you run the first command
- Go to the root directory of Orcid Angular folder and you can run any tx command like
tx statussee [the full CLI docs}(https://docs.transifex.com/client/introduction)
Please note that running tx ini is not required since orcid-angular already have a TX project define at .tx\config
tx push -s
- add
-sto push only source (en) files - add
-tto push translation files - add
-l <lang code>to push a specific language only (defaults to all) - add
-r <resource name>to push a specific resource only (defaults to all)
For additional options/usage http://docs.transifex.com/client/push
Pull only strings that have been marked as reviewed in Transifex
tx pull --mode reviewed
For additional options/usage, see http://docs.transifex.com/client/pull. Note that the pull commands might create empty strings, or use the source string for untranslated strings, please do not commit these.
When new translations have been added directly to the repository (for instance by a yarn build:i18n:clone ...), the new translations can be pushed with
push -r <resource name> -s -t
When only a specific language translation needs to be pushed
push -r <resource name> -s -t -l <lang code>
When new translations are available on Transifex and need to be available before the file is 100% translated
tx pull -a --mode onlytranslated
It is possible to apply modifications to the text on compilation time.
For instance, adding the key #upperCase before the translation key
<button i18n="#upperCase@@helloWorld">Hello!</button>
Will transform the translated text on every language to uppercase before using it to build the application.
The following transformations keys are available
| Key | Initial text | Processed text |
|---|---|---|
| #upperCase | test | TEST |
| #lowerCase | TEST | test |
| #titleCase | test tile | Test Tile |
| #sentenceCase | test sentence | Test sentence |
If more preprocessing methods are required those can be added on the function translationTreatment on /src/locale/translate-file-generator.ts
To find possible problems on translations the file src\locale\messages.translation.log.json is generated on compilation time, or by just running yarn build:i18n. It contains a list of objects for every supported i18n code with the following parameters:
| Parameter | Description |
|---|---|
| notFound | A list of unexisting translation IDs on the properties files. |
| unexistingFiles | A list of unexisting translations files that were expected for the language. |
| changed | A list of objects that represent the translations that were altered through the script. Each contains the translation id, the original translation on the properties files, and the replacement that the script sets. |
| unmatch | This parameter can only be present on the English language en, it shows which translations do not match between the templates and the English properties files. Each contains the id of the translation, textOnTemplate and textOnProperty This is the best way to find translation keys which value doesn't match the value on the template. |
To test translations it is required to serve the application with AOT compilation. For this, please make sure to build the translations with yarn build:i18n and call any of the scripts for the supported languages.
yarn start:aot ## Runs the application in using the English properties
yarn start:fr ## Runs the application in using the French properties
yarn start:ar ## Runs the application in using the Arabic properties
yarn start:es ## Runs the application in using the Spanish properties
yarn start:ca ## ... and so on
yarn start:cs
yarn start:it
yarn start:ja
yarn start:pt
yarn start:ru
yarn start:uk
yarn start:zh_CN
yarn start:zh_TW
yarn start:lr ## These last fourth configurations are used only for testing
yarn start:rl
yarn start:xx
yarn start:source
When running the application with "yarn start" the language en-us is used, this language is based on the template strings. This is not the same as the en language, which is the one used on QA, sandbox, production, and by yarn start:aot, which is based on the manually maintained <module-name>.en.properties files sync with Transifex.
Having this duplication of the English language helps catch errors like using the same id for two different strings on the templates, that is detectable on the messages.translation.log.json file at the en/unmatch attribute. This should be kept until angular enables throwing errors when there a use of the same id with different contents.