Translating projectops
projectops writes a few messages into your repository: issue and PR templates, bot comments, release-notes notices, the CHANGELOG.md header and workflow commit messages. English is the source language. Any other language is added by adding files plus one line in a list (step 3 below).
The language of a repository is options.language in version.yml:
metadata:
template:
options:
language: en # en | ko | ...- New installs get
en. Existing installs without the key keepko, so an update never changes the wording in a repository that already uses it. - Change it with
npx projectops --language <code>. - A message that is missing in a language falls back to English. A partial translation never breaks a workflow, so you can contribute a few messages at a time.
Add a language
Pick the language code (ja, zh-CN, de, ...). Three things:
- Message catalog. Copy
.github/scripts/i18n/en.jsonto.github/scripts/i18n/<code>.jsonand translate the values. You may delete keys you have not translated yet. - Template overlay. Copy the Korean overlay folder
.github/i18n/ko/to.github/i18n/<code>/and translate the issue and PR templates. Keep the structure identical (sections,labels,assignees, the[Tag]in the title examples). A test compares the structure with the English templates. - One line in the language list. Add the code to
REPO_LANGUAGESinsrc/core/repo-language.js. The list must match the files; a test fails if they disagree. Theversion.ymlparser,--languagevalidation andnpx projectops --mode optionsall read this list, so nothing else needs the code. The comments written intoversion.ymlfall back to English until you add a block for your language toCOMMENTS(and a header) insrc/core/version-yml.js— optional, and it never breaks anything.
Run the checks:
npm testRules for messages
- Keys look like
area.event.part(for exampleqa_bot.comment.created). Keep keys identical across languages. - Use
{name}placeholders only. Every placeholder in the English text must appear in your translation, and you must not add new ones. Do not translate the placeholder names. - Do not put these strings in a catalog. Older workflows already installed in other repositories read them with regular expressions, so they are never translated. They live in
.github/scripts/i18n/contracts.py:### 브랜치,Guide by ProjectOps,Guide by SUH-LAB,Summary by CodeRabbit. - Do not write
[skip ci]in a message. The workflow appends it. - Keep Markdown structure (headings, tables, code blocks) the same as English.
What is not translated yet
Log lines in the Actions tab, the util wizards (HTML) and the skills are still Korean or English only. They are tracked in issue #769.
The docs site has every guide in English (docs/en/, served at the site root) and Korean (docs/*.md, served under /ko/). A new guide needs both files with the same slug, so the language switch lands on the same page. Demo GIFs follow the same rule (name.gif English, name.ko.gif Korean) and are recorded with the scripts in docs/recording/.
README translations
docs/i18n/README.{ko,ja,zh-CN}.md follow README.md by hand. The first line of each records the README.md commit it matches: <!-- translated-from: README.md@<commit> -->. After you change README.md, run python3 scripts/check_readme_translations.py: it lists the README.md commits a translation has not caught up with (release bot commits that only touch the version line are ignored; --strict exits 1 when one is behind). It is not run in CI. After you carry the changes into a translation, set its marker to the newest README.md commit (git log -1 --format=%h -- README.md).