-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
ref(i18n): update translations (#116)
ref(i18n): update translations (#116) ref(i18n): deploy from the deploy directory (#116) ref(i18n): reorg task file (#116) ref(i18n): improve task file for i18n (#116)
- Loading branch information
1 parent
ffc797c
commit 7e5d425
Showing
15 changed files
with
406 additions
and
98 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| # 🌐 i18n Assistance | ||
|
|
||
| This document aims to augment that which appears in the [goi18n project](https://github.com/nicksnyder/go-i18n/) and provide information that can help the client use the i18n functionality defined there and its integration into this template project. The translations process is quite laborious, so this project tries alleviate this process by providing helper tasks which will be documented here also. | ||
|
|
||
| ## 📁 Directory Structure | ||
|
|
||
| The local directory structure is as follows: | ||
|
|
||
| - ___default___: contains the translation file created by the __newt__ (new translation task). Actually, this task creates an __active__ file (`active.en-GB.json`) in the `i18n/out` folder, the result of which needs to be manually copied into the __active__ file in the `default` folder. | ||
|
|
||
| - ___deploy___: contains all the translations files that are intended to be deployed with the application. There will be one per supported language and by default this template project includes a translation file for __en-US__ (`arcadia.active.en-US.json`) | ||
|
|
||
| ## ⚙️ Translation Workflow | ||
|
|
||
| ### ✨ New Translations | ||
|
|
||
| __goi18n__ instructs the user to manually create an empty translation message file that they want to add (eg `translate.en-US.json`). This is taken care of by the __newt__ task. Then the requirement is to run the goi18n merge \<active\> command (goi18n merge `arcadia.active.en-US.json` `arcadia.translate.en-US.json`). This has been wrapped up into the __merge__ task and the result is that the translation file `arcadia.translation.en-US.json` is populated with the messages to be translated. So the sequence goes: | ||
|
|
||
| - run __newt__ task: (generates default language file `./src/i18n/out/active.en-GB.json` and empty `./src/i18n/out/us-US/arcadia.translation.en-US.json` file). This task can be run from the root folder, __goi18n__ will recursively search the directory tree for files with translate-able content, ie files with template definitions (___i18n.Message___) | ||
| - run __merge__ task: derives a translation file for the requested language __en-US__ using 2 files as inputs: source active file (`./src/i18n/out/active.en-GB.json`) and the empty __en-US__ translate file (`./src/i18n/out/us-US/arcadia.translation.en-US.json`), both of which were generated in the previous step. | ||
| - hand the translate file to your translator for them to translate | ||
| - rename the translate file to the active equivalent (`arcadia.translation.en-US.json`). Save this into the __deploy__ folder. This file will be deployed with the application. | ||
|
|
||
| ### 🧩 Update Existing Translations (⚠️ not finalised) | ||
|
|
||
| __goi18n__ instructs the user to run the following steps: | ||
|
|
||
| 1. Run `goi18n extract` to update `active.en.toml` with the new messages. | ||
| 2. Run `goi18n merge active.*.toml` to generate updated `translate.*.toml` files. | ||
| 3. Translate all the messages in the `translate.*.toml` files. | ||
| 4. Run `goi18n merge active.*.toml translate.*.toml` to merge the translated messages into the active message files. | ||
|
|
||
| ___The above description is way too vague and ambiguous. It is for this reason that this process has not been finalised. The intention will be to upgrade the instructions as time goes by and experience is gained.___ | ||
|
|
||
| However, in this template, the user can execute the following steps: | ||
|
|
||
| - run task __update__: this will re-extract messages into `active.en-GB.json` and then runs merge to create an updated translate file. | ||
| - hand the translate file to your translator for them to translate | ||
| - as before, this translated file should be used to update the active file `arcadia.active.en-US.json` inside the __deploy__ folder. | ||
|
|
||
| ## 🎓 Task Reference | ||
|
|
||
| ❗This is a work in progress ... | ||
|
|
||
| ### 💤 extract | ||
|
|
||
| Scans the code base for messages and extracts them into __out/active.en-GB.json__ (The name of the file can't be controlled, it is derived from the language specified). No need to call this task directly. | ||
|
|
||
| ### 💠 newt | ||
|
|
||
| Invokes the `extract` task to extract messages from code. After running this task, the __translate.en-US.json__ file is empty ready to be used as one of the inputs to the merge task (_why do we need an empty input file for the merge? Perhaps the input file instructs the language tag to goi18n_). | ||
|
|
||
| Inputs: | ||
|
|
||
| - source code | ||
|
|
||
| Outputs: | ||
|
|
||
| - ./src/i18n/out/active.en-GB.json (messages extracted from code, without hashes) | ||
| - ./src/i18n/out/en-US/translate.en-US.json (empty) | ||
|
|
||
| ### 💠 merge | ||
|
|
||
| Inputs: | ||
|
|
||
| - ./src/i18n/out/active.en-GB.json | ||
| - ./src/i18n/out/en-US/arcadia.translate-en-US.json | ||
|
|
||
| Outputs: | ||
|
|
||
| - ./src/i18n/out/active.en-US.json | ||
| - ./src/i18n/out/translate.en-US.json |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| { | ||
| "foo-bar.arcadia.nav": { | ||
| "description": "Foo Bar description", | ||
| "other": "foo bar failure '{{.Path}}' (reason: {{.Reason}})" | ||
| }, | ||
| "root-command-config-file-usage": { | ||
| "description": "root command config flag usage", | ||
| "other": "config file (default is $HOME/{{.ConfigFileName}}.yml)" | ||
| }, | ||
| "root-command-language-usage": { | ||
| "description": "root command lang usage", | ||
| "other": "'lang' defines the language according to IETF BCP 47" | ||
| }, | ||
| "root-command-long-description": { | ||
| "description": "long description for the root command", | ||
| "other": "A longer description that spans multiple lines and likely contains\n\t\texamples and usage of using your application. For example:\n\t\t\n\t\tCobra is a CLI library for Go that empowers applications.\n\t\tThis application is a tool to generate the needed files\n\t\tto quickly create a Cobra application." | ||
| }, | ||
| "root-command-short-description": { | ||
| "description": "short description for the root command", | ||
| "other": "A brief description of your application" | ||
| }, | ||
| "using-config-file": { | ||
| "description": "Message to indicate which config is being used", | ||
| "other": "Using config file: {{.ConfigFileName}}" | ||
| } | ||
| } |
Oops, something went wrong.