aws-samples / aws-samples/eks-workshop-v2

Translations to other languages

Open
#1,398 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
HCL
Stars
626
Forks
613
Avg merge
2d 7h
Merged PRs (30d)
9

Description

### What would you like to be added?

The workshop content should be offered in other languages, but has historically represented complexity that would hinder our ability to maintain the workshop at the velocity that we do. Generative AI now offers the opportunity to automate content translation at scale in a repeatable manner.

The first language to be targeted will be Japanese. With these languages considered as follow-ups:

- French
- Spanish
- Portugues
- Korean

Requirements:
- The process must be repeatable, either in response to merge events or as part of the release process
- It should be possible to provide per-language instructions to the LLM to account for language-specific details
- Consistency is desired so the translations don't potentially change drastically between each release

Implementation:

The plan is to use [toolkit-md](https://github.com/awslabs/toolkit-md) to perform the translation of the Markdown content itself as it has mechanism to help with on-going maintenance of the translated content.

There are perceived to be two phases of implementation:

**1. Onboarding**

Adding a new language involves some "one-time" setup, as documented in the Docusaurus docs:

https://docusaurus.io/docs/i18n/git

This includes:
1. Add the locale to `docusaurus.config.js`
2. Initialize the `i18n` directory for the locale with `yarn write-translations --locale [...]`
3. Translate various static parts of the site like the homepage, menu, footer etc.
4. Establish a language-specific style guide for translations in the `i18n` directory
5. Perform an initial translation of the Markdown content

**2. Translation updates**

As content written in English is added or updated the translated content will need to be updated. The plan is to handle this with a GitHub Actions workflow that runs on merge events to the `main` branch. The workflow will run `toolkit-md` for a matrix of languages in order to ensure the 60 minute time limit of IAM credentials is not breached. Once all the language steps are completed the workflow can consolidate the various files in to a step that will commit changes to a branch and create/update a PR. Subsequent runs will rebase the same branch and re-translate.

The PR can then be merged before the monthly release process.

### Why is this needed?

We have had sporadic requests to translate the workshop to other languages.

Contributor guide

Open the contributing guide

Research direction

Start with docusaurus.config.js, the Docusaurus GitHub i18n documentation, and toolkit-md. Define the Japanese locale, initialize its i18n content and style guide, then design the GitHub Actions workflow for repeatable translation updates and PR creation. Done means Japanese content is translated and the update process is repeatable before release.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, javascript, markdown
Domain
ci-cd, documentation, localization
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.