Prompt file imported from Luyi365/awesome-embedded (.github/prompts/i18n.prompt.md). Copyright stays with the author.

Localize Embedded README Files

Translate this repository's embedded-systems README documentation while preserving its Markdown mechanics. The normal task is to translate a Simplified Chinese README.md and its linked local appendices into one or more sibling language variants, then keep language navigation and local links correct.

Inputs And Defaults

• Source README: use the requested directory's README.md; for a repository-wide request, use the root README.md.
• Source language: Simplified Chinese unless the source clearly indicates otherwise.
• Target languages: use the languages named by the user. If absent, inspect existing variants and selectors; ask once if still unclear. Never invent target languages.
• Terminology: apply any provided glossary, preferred wording, or do-not-translate list consistently.
• Naming: README.md is the canonical Chinese source. Create target files as README.<bcp47-tag>.md, for example README.en.md, README.ja.md, and README.zh-Hant.md.

Preserve an established multilingual filename convention if it conflicts with these defaults.

Translation Boundaries

Translate human-facing prose, including headings, paragraphs, list descriptions, table text, visible HTML text, and image or badge labels (alt text) unless they strictly represent a technical identifier, URL endpoint, or standard protocol.

Do not translate inline code, commands, CLI flags, environment variables, URLs, file paths, Markdown/HTML syntax, repository and package names, API identifiers, version identifiers, or badge and image URLs. Preserve established embedded-systems and programming terms such as MCU and RTOS unless the target language has a clearly standard technical equivalent.

Inside fenced code blocks, keep the code itself unchanged — identifiers, keywords, syntax, string literals used as data, and formatting must stay exactly as in the source. However, translate the human-readable comments within the code (for example // 写操作 → // Write operation, #矩阵按键 → # matrix keypad) into the target language, and translate user-facing string literals only when they are clearly display messages meant to be read (not protocol tokens, keys, or identifiers). Preserve comment markers (//, /* */, #), indentation, and alignment; translate only the comment text after the marker.

Style And Tone

Stay faithful to the source. Translate what the source actually says; never invent, embellish, or drop meaning to make a description sound better or more complete. When the source of two paired descriptions differs, do not paper over the difference in translation.

• Reduce, but do not forbid, uniform openings. English descriptions should not all begin with "A"/"An"; vary the phrasing by dropping the article and leading with an adjective or noun, or by opening with a functional verb. This is a preference for variety, not a rule against articles — keep an article when the sentence reads naturally and forcing a change would distort the meaning. Do not rewrite already-faithful sentences solely to remove an article.
• Preserve the source's colloquial voice. Embedded-list descriptions are often informal and personal (for example "just drop it in and you're done", "it feels absolutely cool", "a pretty interesting approach"). Carry that casual tone into the translation instead of flattening it into stiff, formal, or generic "AI-sounding" prose.

Punctuation And Locale Conventions

Use punctuation that matches the target language's locale, and match the established convention already used in the source and sibling variants.

• Full-width languages (Simplified Chinese, Japanese, Traditional Chinese): use full-width punctuation in prose — for example （） for parentheses, ，、。 for commas and periods. Do not leave half-width () around text that sits next to full-width characters.
• Half-width languages (English): use half-width punctuation, including half-width parentheses ().
• Do not change punctuation that lives inside a Markdown link's visible text when that text reproduces a project's own original title or repository description — treat it as part of the untouched link text, even if its punctuation width differs from the surrounding prose.
• Fix obvious source typos you introduce or touch (for example a doubled character), but do not silently rewrite unrelated wording.
• Headings must not end with punctuation (no trailing ?/？, :/：, ./。, etc.), in any language. awesome-lint's no-heading-punctuation rule only detects half-width marks, so a Chinese heading ending in a full-width ？ or ： may pass while its English translation fails — strip the trailing punctuation from both. Removing trailing punctuation does not change a heading's GitHub slug, so existing same-file anchors keep resolving.
• Escape square brackets that appear inside a link's visible text. Chinese sources often use full-width brackets like 【稳定版】 inside a link label, which Markdown ignores; when translating to half-width [...], the inner brackets become an accidental reference-style link and trigger no-undefined-references. Escape them as \[...\] (for example [repo: \[Stable Version\] ...](url)).

Preserve Markdown And Links

1. Read the complete source README and any local documents it links before editing. Identify headings, lists, tables, badges, images, HTML, alerts, comments, code blocks, relative links, and same-file anchors.
2. Keep the source structure and order intact: heading levels, paragraphs, list nesting and indentation, table layout, horizontal rules, code-fence count and language labels, HTML, images, and whitespace-sensitive content. Do not add, remove, reorder, or reformat content solely for translation. (Code-fence structure is preserved, but comments and display strings inside a code block are still translated per the Translation Boundaries rule above.)
3. Translate headings, then rewrite each same-file (#...) link to the GitHub slug generated by the localized heading. Preserve explicit anchors such as <a id="..."> unless the existing convention localizes them.
4. Change a relative README link to its target-language sibling only when that sibling exists. For English use README.en.md; for Chinese use the canonical README.md. Otherwise retain the original target.
5. When a README links to a same-directory appendix.md, translate that appendix as appendix.<bcp47-tag>.md only when it is included in the requested scope. Point the localized README to its localized appendix and anchor. If the appendix is out of scope, preserve the original appendix.md link.
6. Localize external documentation links to the target language when a valid equivalent page exists. A Chinese source often links to a language-specific page — for example zh.wikipedia.org/zh-cn/…, zh.cppreference.com/…, docs.espressif.com/projects/esp-idf/zh_CN/…, learn.microsoft.com/zh-cn/…, openthread.io/?hl=zh-cn, or toml.io/cn/. In a target-language variant, rewrite these to the matching localized URL (English examples: en.wikipedia.org/wiki/…, en.cppreference.com/…, …/esp-idf/en/…, …/en-us/…, ?hl=en, toml.io/en/).
   • Verify every rewritten URL actually resolves before applying it (fetch it and confirm it is not a 404 or a redirect to an unrelated page). If no valid equivalent exists, keep the original link unchanged.
   • Do not rewrite links whose language segment is not a switchable locale: repository file names (for example intro_zh.md — only change to intro_en.md if that file truly exists), project subdomains (for example wiki-zh.luatos.org), or documentation published only in Chinese (for example many domestic vendor docs). Confirm by fetching, then leave them as-is.
   • When you change the URL, also update the link's visible text if it names the language (for example "TensorFlow 中文官网" → "TensorFlow official website").

Separator Rules

Use exactly one separator between a project name or field label and its description. This rule applies to unordered-list project entries and labeled fields such as **链接**： and **特征**：.

• Full-width target languages, including Japanese and Traditional Chinese: use ： immediately after the name, label, or closing Markdown link.

• Half-width target languages, including English: use - immediately after the name, label, or closing Markdown link.

• English examples:

  - [base64](./README.en.md#base64) - A minimal Base64 encoding and decoding library.
  **Link** - [Example repository](https://example.com)
  **Features** - A lightweight embedded library.

Do not otherwise normalize punctuation or alter formatting.

Contents Entry And Features Consistency

Many READMEs describe each project in two places: a short entry in the root/contents list (for example - [wolfIP](...#wolfip) - ...) and a detailed **Features** field on the project's own section. The source keeps these two descriptions textually identical, and every localized variant must preserve that.

1. Translate the description once, then use the exact same wording for both the contents-list entry and the matching **Features** field. Do not paraphrase one differently from the other.
2. Links are the only permitted difference between the two. The **Features** field may embed Markdown links (for example [lwIP](#lwip)); the contents-list entry keeps only the link's visible text and drops the link target (for example plain lwIP). Mirror exactly what the source does: wherever the source **Features** uses a link and the source contents entry uses plain text, reproduce that same split in the translation.
3. When you edit one of the two, update the other in the same pass so they stay identical. Verify the pair matches (aside from links) before finishing.
4. If the two source descriptions are not yet textually identical (aside from links), the source itself needs fixing first: reconcile the Chinese so both places share one wording (keeping the more complete or accurate version, and preserving any useful colloquial phrasing), then translate from the reconciled source. Do not encode a source inconsistency into the translation.

Language Selector

Maintain exactly one selector in every available README variant. Update an existing selector in place; otherwise add it after the opening title, badge, image, or first paragraph of text. Delimit it with these exact markers so subsequent runs can update it deterministically:

<!-- i18n:language-selector:start -->
**中文** | [English](README.en.md)
<!-- i18n:language-selector:end -->

Use the same language order and labels across variants, link every available variant, and emphasize the current language.

Workflow And Verification

1. Establish the source files, target languages, naming pattern, existing variants, selector style, and terminology constraints.

2. Create or update each requested localized README and in-scope appendix. Translate prose only, then update localized anchors and eligible relative links.

3. Add or update the selector across all affected README variants.

4. Before finishing, use an available diff or validation tool to compare every localized README with its source. Verify no headings, horizontal rules, code fences, tables, lists, badge/image URLs, or structural elements were accidentally merged, deleted, or reordered; ensure all localized links and same-file anchors resolve; ensure exactly one selector per variant; and check every project entry and field label uses the correct full-width or half-width separator.

5. This repository targets the Awesome list ecosystem and must pass awesome-lint. Validate any root README you touched. On Windows PowerShell, run it through cmd.exe so stderr is not swallowed:

   cmd.exe /d /c npx awesome-lint README.md
   cmd.exe /d /c npx awesome-lint README.en.md

   Keep these lint rules in mind when writing descriptions:

   • remark-lint:no-repeat-item-in-description: a list-item description must not begin with the project/item name. When the source description opens with the project's own name (common in Chinese, which is not subject to this rule), rephrase the localized description so it does not start with that name, while preserving meaning.
   • remark-lint:no-file-name-mixed-case: this fires on mixed-case filenames such as README.en.md. It conflicts with the required README.<bcp47-tag>.md naming convention and is an accepted known exception — do not rename files to satisfy it.
   • Relative links in list items can trip awesome-list-item / double-link; if the root README wraps its list region in <!--lint disable ...--> / <!--lint enable ...--> comments, keep new entries inside that region and leave the comments intact.

Finish with a concise summary of changed files, source and target languages, selector and localized-link updates, validation results (including awesome-lint status), retained technical terms, and any unresolved translation questions.