Skip to content

Commit

Permalink
docs(i18n): update docs with i18n workflow changes
Browse files Browse the repository at this point in the history
  • Loading branch information
zyf722 committed Nov 1, 2024
1 parent a80f535 commit 68d8997
Showing 1 changed file with 22 additions and 9 deletions.
31 changes: 22 additions & 9 deletions docs/docs/contribution/i18n.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,8 @@ Several npm scripts are available to facilitate the i18n workflow:
- [`i18n-exclude`](../../../scripts/i18n-exclude.js): **(Only used in other scripts and should not be run locally)** Excludes all other i18n locales except for English from type checking, as they might stay outdated and cause errors.
- The `<phase>` argument is required to specify whether the script is to exclude files or revert the exclusion. Valid values are `pre` and `post`.
- This script only works when environment variable `BUILD_INCLUDE_LOCALES` is **NOT** set to `true`.
- [`i18n-lokalise-json`](../../../scripts/i18n-lokalise-json.mjs): Generates `.lokalise.json` files from codebase for manually authoring translations on Lokalise.
- The `<lang>` argument is required to specify the language that the `.lokalise.json` files are generated from.

Please run `i18n-export` before pushing changes to the codebase to ensure that the source texts are up-to-date.

Expand All @@ -183,7 +185,11 @@ We consider the i18n process to consist of two parts:

This means there are no changes to the source code/texts, only translations are updated. Adding new languages or updating existing translations are examples of this part.

In such cases, there is a scheduled workflow [`i18n-update-scheduled`](../../../.github\workflows\i18n-update-scheduled.yml) to handle this. The workflow will sync between the `master` branch on Lokalise and the `i18n/develop` branch on the codebase, then automatically create a PR if there are any changes. Basically, maintainers do not need to pay too much attention to this part except for reviewing the PRs.
In such cases, there is a scheduled workflow [`i18n-update-scheduled`](../../../.github/workflows/i18n-update-scheduled.yml) to handle this. The workflow will sync from the `master` branch on Lokalise to the `i18n/develop` branch on the codebase, then automatically create a PR if there are any changes.

Basically, maintainers only need to focus on the following for this part:
- Reviewing PRs created by the `i18n-update-scheduled` workflow
- Do merging on Lokalise after they consider the translation for a specific feature is ready, before commenting `.i18n-update-pull` to trigger the `i18n-update-pull` workflow

#### Source Update

Expand All @@ -193,18 +199,18 @@ This means new changes are made to the source code/texts. In this case, maintain
2. Once a new feature or version is ready, developers run `npm run i18n-export` to extract and update all marked strings, then export them to `.lokalise.json` and `.ts` files.
3. Developers commit and push the changes to the repository. A feature PR is created and reviewed, and related tests, checks, and manual review could be carried out.
4. After the PR is merged, an auto-generated comment will notify maintainers to comment `.i18n-update-push` to trigger the `i18n-update-push` workflow when they think it is ready.
5. Maintainers comment `.i18n-update-push` to trigger the `i18n-update-push` workflow. The workflow will create a new branch named `i18n/<head-branch>`, run `npm run i18n-export` again to ensure the source texts are up-to-date, and push the changes. Then, it will push the changes to the `i18n/<head-branch>` branch on Lokalise.
5. Maintainers comment `.i18n-update-push` to trigger the `i18n-update-push` workflow. The workflow will create a new branch named `i18n/<owner>/<head-branch>`, run `npm run i18n-export` again to ensure the source texts are up-to-date, and push the changes. Then, it will push the changes to the `i18n/<owner>/<head-branch>` branch on Lokalise.
6. Translators can start translating the texts on Lokalise.
7. Once the translation is complete, maintainers can comment `.i18n-update-pull` to trigger the `i18n-update-pull` workflow. The workflow will pull the translated texts from Lokalise, update the `.ts` files under `src/livecodes/i18n/locales`, and commit the changes to the `i18n/<head-branch>` branch. Then, it will create a PR to merge the changes back to the default branch `develop`.
8. Maintainers should perform a final review on the i18n PR and merge it if everything is fine.
7. Once the translation is complete, maintainers can comment `.i18n-update-pull` to trigger the `i18n-update-pull` workflow. The workflow will pull the translated texts from Lokalise, update the `.ts` files under `src/livecodes/i18n/locales`, and commit the changes to the `i18n/<owner>/<head-branch>` branch. Then, it will create a PR to merge the changes back to the default branch `develop`.
8. Maintainers should perform a final review on the i18n PR and merge it if everything is fine. Meanwhile, a merging from the `i18n/<owner>/<head-branch>` to `master` should also be done to keep the `master` branch on Lokalise up-to-date.

### Github Actions (CI)

Four i18n-related workflows are set up in the repository:

- [`i18n-update-notify`](../../../.github\workflows\i18n-update-notify.yml): Creates a comment on merged PRs to notify maintainers to trigger the `i18n-update-push` workflow.
- [`i18n-update-push`](../../../.github\workflows\i18n-update-push.yml): Creates a new branch named `i18n/<head-branch>`, runs `npm run i18n-export` again to ensure the source texts are up-to-date, pushes the changes on git, then pushes the changes to the `i18n/<head-branch>` branch on Lokalise.
- [`i18n-update-pull`](../../../.github\workflows\i18n-update-pull.yml): Pulls the translated texts from Lokalise, updates the `.ts` files under `src/livecodes/i18n/locales`, commits the changes to the `i18n/<head-branch>` branch, then creates a PR to merge the changes back to the default branch `develop`.
- [`i18n-update-push`](../../../.github\workflows\i18n-update-push.yml): Creates a new branch named `i18n/<owner>/<head-branch>`, runs `npm run i18n-export` again to ensure the source texts are up-to-date, pushes the changes on git, then pushes the changes to the `i18n/<owner>/<head-branch>` branch on Lokalise.
- [`i18n-update-pull`](../../../.github\workflows\i18n-update-pull.yml): Pulls the translated texts from Lokalise, updates the `.ts` files under `src/livecodes/i18n/locales`, commits the changes to the `i18n/<owner>/<head-branch>` branch, then creates a PR to merge the changes back to the default branch `develop`.
- [`i18n-update-scheduled`](../../../.github\workflows\i18n-update-scheduled.yml): Syncs between the `master` branch on Lokalise and the `i18n/develop` branch on the codebase, then automatically creates a PR if there are any changes.

### Hashing and Cache
Expand All @@ -225,8 +231,15 @@ File hashing is also applied to translation files during build, by auto-generati

## For Those Who Forked the Repo

To ensure the i18n workflow functions properly, `Workflow permissions` in `Settings > Actions > General` should be set to `Read and write permissions`, and make sure that `Allow GitHub Actions to create and approve pull requests` is enabled.
This repository is utilizing [LiveCodes CI](https://github.com/apps/livecodes-ci) Github App to ensure the i18n workflow functions properly.

For forked repositories, maintainers should set up their own Lokalise project and Github App (see [here](https://github.com/peter-evans/create-pull-request/blob/main/docs/concepts-guidelines.md#authenticating-with-github-app-generated-tokens)) to handle the i18n workflow. Changes to related workflow files are necessary.

`LOKALISE_API_TOKEN` should be set as a repository secret, while `LOKALISE_PROJECT_ID` should be set as a repository variable.
### Secrets and Variables Checklist
#### Repository Secrets
- `LOKALISE_API_TOKEN`
- `CI_APP_ID`
- `CI_APP_PRIVATE_KEY`

For private forks, `GITHUB_TOKEN` in workflow files should be set to a personal access token (PAT) with proper permissions.
#### Repository Variables
- `LOKALISE_PROJECT_ID`

0 comments on commit 68d8997

Please sign in to comment.