From 49884aec930d4439a7f50b49e91f54b2ed06d5cd Mon Sep 17 00:00:00 2001 From: Xi Xu Date: Sat, 28 Mar 2026 18:30:55 +0800 Subject: [PATCH] feat(readme-i18n): add README localization skill --- README.md | 1 + README.zh.md | 1 + skills/readme-i18n/SKILL.md | 178 ++++++++++++++++++ .../references/language-selector-reference.md | 79 ++++++++ .../references/preservation-checklist.md | 26 +++ 5 files changed, 285 insertions(+) create mode 100644 skills/readme-i18n/SKILL.md create mode 100644 skills/readme-i18n/references/language-selector-reference.md create mode 100644 skills/readme-i18n/references/preservation-checklist.md diff --git a/README.md b/README.md index 3aaee69..1eb5ba5 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,7 @@ The table below lists the skills maintained across this repository and the relat | [github-actions-docs](./skills/github-actions-docs/SKILL.md) | Official-docs-grounded help for writing, migrating, securing, and troubleshooting GitHub Actions workflows. | `references/` | | [openclaw-secure-linux-cloud](./skills/openclaw-secure-linux-cloud/SKILL.md) | Guidance for securely self-hosting OpenClaw on Linux VPS or cloud servers. | `references/` | | [opensource-guide-coach](./skills/opensource-guide-coach/SKILL.md) | Coaching for starting, growing, governing, funding, and sustaining open source projects. | `references/` | +| [readme-i18n](./skills/readme-i18n/SKILL.md) | Help for translating repository READMEs, adding localized README variants, and wiring a language selector without breaking Markdown mechanics. | `references/` | | [running-claude-code-via-litellm-copilot](./skills/running-claude-code-via-litellm-copilot/SKILL.md) | Help for routing Claude Code through LiteLLM and GitHub Copilot, including setup and troubleshooting. | `references/` | | [secure-linux-web-hosting](./skills/secure-linux-web-hosting/SKILL.md) | Practical Linux VPS and web hosting hardening for DNS, SSH, reverse proxies, HTTPS, and safe self-hosting. | `references/` | | [skills-cli](./skills/skills-cli/SKILL.md) | Help for discovering, installing, listing, backing up, restoring, syncing, and managing Agent Skills. | None | diff --git a/README.zh.md b/README.zh.md index bd7ea85..03ac98a 100644 --- a/README.zh.md +++ b/README.zh.md @@ -65,6 +65,7 @@ npx skills add xixu-me/xdrop | [github-actions-docs](./skills/github-actions-docs/SKILL.md) | 基于官方文档，帮助编写、迁移、加固和排查 GitHub Actions workflows。 | `references/` | | [openclaw-secure-linux-cloud](./skills/openclaw-secure-linux-cloud/SKILL.md) | 为在 Linux VPS 或云服务器上安全自托管 OpenClaw 提供指导。 | `references/` | | [opensource-guide-coach](./skills/opensource-guide-coach/SKILL.md) | 为开源项目的启动、增长、治理、资助与长期维护提供辅导。 | `references/` | +| [readme-i18n](./skills/readme-i18n/SKILL.md) | 帮助翻译存储库 README、维护多语言 README 变体，并在不破坏 Markdown 结构的前提下添加语言切换器。 | `references/` | | [running-claude-code-via-litellm-copilot](./skills/running-claude-code-via-litellm-copilot/SKILL.md) | 帮助通过 LiteLLM 和 GitHub Copilot 路由 Claude Code，包括安装配置与排障。 | `references/` | | [secure-linux-web-hosting](./skills/secure-linux-web-hosting/SKILL.md) | 提供 DNS、SSH、反向代理、HTTPS 和安全自托管相关的 Linux VPS / Web Hosting 实践指南。 | `references/` | | [skills-cli](./skills/skills-cli/SKILL.md) | 帮助发现、安装、列出、备份、恢复、同步和管理 Agent Skills。 | 无 | diff --git a/skills/readme-i18n/SKILL.md b/skills/readme-i18n/SKILL.md new file mode 100644 index 0000000..dcffdf9 --- /dev/null +++ b/skills/readme-i18n/SKILL.md @@ -0,0 +1,178 @@ +--- +name: readme-i18n +description: Use when the user wants to translate a repository README, make a repo multilingual, localize docs, add a language switcher, internationalize the README, or update localized README variants in a GitHub-style repository. +--- + +# README Internationalization (i18n) + +Localize a repository `README.md` without breaking the repo mechanics around it. + +The default job is translate + wire-up: + +- read the source-of-truth README +- create localized sibling files such as `README.zh.md` +- preserve GitHub-flavored Markdown structure and repo-specific tokens +- add or update a shared language selector near the top of every variant + +This skill is for multilingual README workflows, not general website/app i18n. + +## Inputs + +Expect these inputs when available: + +- source README path, default `README.md` +- source language, default inferred or English +- one or more target languages +- optional glossary or do-not-translate list +- optional filename override if the repo already uses a different multilingual naming pattern + +If target languages are not named, inspect existing translated files, selectors, filenames, issues, or prior repo conventions. If that still leaves the target languages unclear, ask once. Do not invent target languages. + +## Defaults And Decision Rules + +- Treat the root `README.md` as the source-of-truth unless the user explicitly says otherwise. +- If the source language is ambiguous, ask once. Otherwise assume English. +- Keep section order aligned with the source README. Only make a small heading wording adjustment when needed to produce a valid localized anchor. +- Output localized siblings with `README..md` naming unless the repo already has a different established pattern that should be preserved. +- Update an existing language selector in place. Do not duplicate it. +- Translate only human-language content. +- Preserve project names, package names, commands, CLI flags, option names, environment variables, URLs, file paths, inline code, code fences, HTML attributes, and badge/image URLs. +- Badge alt text or visible labels may be translated only when the change does not require changing the badge URL, query params, or image source. +- If a glossary or do-not-translate list is provided, apply it consistently across every target language. + +## Workflow + +### 1. Establish the source README and languages + +- Confirm the source README path. Default to `README.md`. +- Identify the source language from the file contents and repo context. +- Determine target languages from the request or existing repo pattern. +- Note any glossary terms, product names, or phrases that must stay untranslated. + +### 2. Audit the Markdown structure before translating + +Read the source README once as structure, not prose. Open [references/preservation-checklist.md](references/preservation-checklist.md) and inventory the elements most likely to break: + +- headings and heading levels +- badge rows, shields URLs, and image links +- tables and alignment rows +- raw HTML blocks and inline HTML +- GitHub alerts or admonitions such as `> [!NOTE]` +- code fences, inline code, commands, and config snippets +- intra-document anchors such as `(#installation)` +- relative links to files, docs, screenshots, or other README variants + +If the README already has localized siblings, inspect them too before choosing filenames or selector style. + +### 3. Translate only the prose layer + +Translate: + +- paragraph text +- list item prose +- table cell prose +- visible text inside HTML blocks +- image alt text when safe +- selector labels and other human-facing labels + +Do not translate: + +- fenced code blocks +- inline code spans +- shell commands +- flags such as `--help` +- env vars such as `OPENAI_API_KEY` +- URLs +- file paths +- repo/package/project identifiers +- badge and image URLs + +When in doubt, preserve the literal token and translate the surrounding sentence instead. + +### 4. Preserve structure while writing the localized README + +- Keep the same heading hierarchy and section order as the source. +- Keep the same number of code fences unless the user explicitly asks to rewrite examples. +- Preserve table shape, list nesting, HTML wrappers, and Markdown comments. +- Preserve relative links unless a link intentionally needs to point at a localized sibling README. + +### 5. Rewrite localized anchors and anchor-dependent links + +When a translated heading changes, GitHub will generate a different heading ID. After translating headings: + +- rewrite every same-file `(#...)` link so it matches the localized heading slug in that file +- preserve custom explicit anchors such as `` unless the file already uses localized explicit IDs +- verify that every intra-document anchor target resolves to an existing heading or explicit anchor + +Prefer a small heading wording adjustment over a broken anchor. The section order should still match the source README. + +### 6. Write sibling files using the repo's naming pattern + +Default to sibling filenames like: + +- `README.zh.md` +- `README.es.md` +- `README.fr.md` + +If the repo already uses a different multilingual naming pattern, keep using it consistently rather than forcing the default pattern. + +### 7. Insert or update the language selector + +Open [references/language-selector-reference.md](references/language-selector-reference.md) before editing selectors. + +Placement: + +- keep the selector near the top of the file +- if the README starts with a title, badges, hero image, or short intro block, place the selector immediately after that opening cluster + +Behavior: + +- update an existing selector block in place if one already exists +- if you add a new selector, use the canonical marker comments from the reference file so later runs can update it deterministically +- emphasize the current language and link the other variants +- keep selector order and labels consistent across every README variant + +### 8. Final verification + +Before finishing, verify: + +- localized filenames follow the chosen pattern +- every README variant contains exactly one selector block +- code fence counts are preserved +- badge/image URLs and relative file links still point to the original targets unless intentionally localized +- every `(#...)` link resolves inside its own file +- the localized README still feels structurally identical to the source + +## Output + +Produce: + +- one localized sibling README per target language +- an updated selector block in every README variant +- a brief note to the user covering created or updated files, any assumptions, and any terms intentionally left untranslated + +## Maintenance Note + +Keep `README.md` as the canonical source unless the user says otherwise. When the source README changes later, update each localized sibling by diffing the changed prose, then re-check selectors, filenames, and anchor links instead of reformatting the whole file from scratch. + +## Example Prompts + +**Example 1** + +`Translate this README into Chinese and add a language switcher. Keep badge URLs, code fences, and all commands exactly as they are.` + +**Example 2** + +`Make the repo multilingual. Add Spanish and Chinese README variants, keep the internal anchor links working, and wire the selector into every file.` + +**Example 3** + +`We already have README.zh.md. Add README.es.md and update the existing selector in place instead of adding a second one.` + +## Common Mistakes + +- Translating fenced code blocks or inline code instead of only the prose around them +- Duplicating the language selector instead of updating the existing block +- Translating a heading but forgetting to rewrite same-file `(#...)` links +- Changing badge URLs or image sources while trying to translate visible labels +- Reordering sections in the localized README even though the source README is the authority diff --git a/skills/readme-i18n/references/language-selector-reference.md b/skills/readme-i18n/references/language-selector-reference.md new file mode 100644 index 0000000..0631d90 --- /dev/null +++ b/skills/readme-i18n/references/language-selector-reference.md @@ -0,0 +1,79 @@ +# Language Selector Reference + +Use one selector block near the top of every README variant. + +## Placement + +- Put the selector immediately after the opening title and badge cluster. +- If the file opens with a hero image, HTML banner, or short intro block, place the selector right after that opening block. +- Keep the selector position consistent across all variants. + +## Canonical Selector Block + +When adding a new selector, use these markers so future runs can update it in place: + +```md + + +**English** | [汉语](README.zh.md) | [Español](README.es.md) + + +``` + +Rules: + +- The current language is emphasized and not linked. +- Other languages are linked. +- Use human-readable autonyms when practical, for example `English`, `汉语`, `Español`, `Français`. +- Keep the same language order in every file. + +## Updating Existing Selectors + +- If a selector already uses `README-I18N` markers, replace only the contents inside that block. +- If the README has an obvious unmarked language switcher near the top, normalize it in place rather than inserting a second selector elsewhere. +- Do not leave multiple selector blocks in the same README. + +## Filename Pattern + +Default localized sibling naming: + +```text +README.md +README.zh.md +README.es.md +README.fr.md +``` + +If the repository already uses another multilingual naming scheme, preserve that existing scheme instead of forcing the default. + +## Variant Examples + +Current file: `README.md` + +```md + + +**English** | [汉语](README.zh.md) | [Español](README.es.md) + + +``` + +Current file: `README.zh.md` + +```md + + +[English](README.md) | **汉语** | [Español](README.es.md) + + +``` + +Current file: `README.es.md` + +```md + + +[English](README.md) | [汉语](README.zh.md) | **Español** + + +``` diff --git a/skills/readme-i18n/references/preservation-checklist.md b/skills/readme-i18n/references/preservation-checklist.md new file mode 100644 index 0000000..3e1e7c1 --- /dev/null +++ b/skills/readme-i18n/references/preservation-checklist.md @@ -0,0 +1,26 @@ +# README Preservation Checklist + +Use this checklist before and after translating a README. + +| Element | Translate? | Preserve exactly | What to verify | +| ------------------------- | ------------------- | ---------------------------------------- | ----------------------------------------------------------------- | +| Headings | Yes, visible text | Heading level and order | Same hierarchy; anchor links updated for localized headings | +| Paragraphs and lists | Yes | Markdown structure | Lists still nest and render like the source | +| Inline code | No | Backticks and literal content | Commands, flags, paths, env vars unchanged | +| Fenced code blocks | No | Fence markers, language tags, code | Same count and same code content | +| Badge markdown | Usually no | Image URL, target URL, query params | Visible label changes do not alter URL mechanics | +| Images | Alt text sometimes | Image source URL and relative path | Image links still resolve | +| Tables | Yes for prose cells | Column count, separator row, alignment | Table shape matches the source | +| Raw HTML blocks | Visible text only | Tags, attributes, wrappers, IDs, classes | HTML still renders and custom anchors survive | +| GitHub alerts | Body text only | Alert marker such as `[!NOTE]` | Alert syntax remains valid | +| Relative file links | Usually no | Link destination path | Links still point at the same file unless intentionally localized | +| Same-file anchors | Link text sometimes | Link intent | Every `(#...)` target exists after heading translation | +| HTML comments and markers | No | Marker text | Existing selector markers remain single and intact | + +## Fast Pass + +- Count code fences before and after. +- Scan for `](#` and verify each target still exists. +- Search for `README.` links and confirm selector links point at the intended siblings. +- Search for `http` and confirm badge/image URLs were not mutated. +- Search for backticks and spot-check that literal tokens stayed literal.