translate
Translation helper for README and documentation files with diff preview and guidance
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- lang
- ko
- name
- translate
- tier
- { "claude": "medium", "gemini-cli": "medium", "antigravity": "medium" }
- owner
- pm
- scope
- co-safety
- status
- active
- version
- 1.0.2
- metadata
- { "type": "process", "triggers": [ "translate", "translation", "Korean translation" ] }
- lifecycle
- { "phase": "production", "created": 1780099200000, "last_updated": 1787529600000 }
- relates_to
- [ { "type": "composes_with", "skill": "documentation-writing" } ]
- description
- Translation helper for README and documentation files with diff preview and guidance
- lang_reason
- legal
- last_updated
- 1787529600000
- last_reviewed
- 1787529600000
03 SKILL.md 正文
Purpose
Provides translation helpers for README and documentation files with diff preview, synchronization checking, and translation guidance.
This is NOT an automatic translation tool - it's a helper tool that assists translators in identifying changes and managing translation work systematically.
Scope boundary: this skill is a file-translation process helper (hash sync, diff preview).
Questions about locale configuration (BCP 47 IDs, collation), locale-specific formatting
(dates, numbers, currency, units), or text layout/encoding (RTL, scripts, fonts) belong to
the i18n asset suite — see the workspace constitution §4.4 "I18N Asset Suite" (governance
corpus) and the i18n skills of the same suite. The localize trigger was removed from
this skill for that reason (2026-08-24).
Implementation
Calls the underlying script:
bun scripts/translate-readme.ts "$@"
Usage
Basic Command (README.md → README_ko.md)
/translate
Default values:
- Source file (
--from):README.md - Target file (
--to):README_ko.md
Translate Different Files
/translate CONTRIBUTING.md CONTRIBUTING_ko.md
Preview Mode (Dry Run)
/translate --dry-run
Shows changes without modifying files.
With Source/Target Flags
/translate --from README.md --to README_ko.md --dry-run
audit_exception: safety-os-skill-structure — Safety OS skills use the legal_basis-gated SSOT skill format (validated by scripts/skill-lifecycle-audit.ts and scripts/validate-skills.ts), not the generic template 5-section/7-frontmatter schema
Understanding Output
1. Hash Synchronization Status
✅ Files are already synchronized (hash: a1b2c3d4e5f6…).
No translation updates needed.
If you see this message, your translation is up-to-date. No action needed.
⚠️ Warning: Content hashes are out of sync!
Source content_hash: a1b2c3d4e5f6…
Target translated_from_hash: 9f8e7d6c5b4a…
If hashes don't match, the source file has changed and translation update is needed.
2. Change Detection Sections
Changes detected:
➕ New section: "Design Principles" (line 45)
✏️ Modified section: "Quick Start" (lines 20-35)
🗑️ Deleted section: "Legacy Content" (line 100)
- ➕ New section: New section added in source (translation needed)
- ✏️ Modified section: Modified section (translation update needed)
- 🗑️ Deleted section: Section deleted from source (should delete from translation)
3. Diff Preview
Diff preview:
------------------------------------------------------------
--- a/README.md
+++ b/README_ko.md
@@ -20,7 +20,7 @@
## Quick Start
-### 1. Install prerequisites
+### 1. Install prerequisites (Bun required)
| Tool | Version | Purpose | Install |
------------------------------------------------------------
Shows Git-style diff:
- Lines starting with
-: Content deleted from source - Lines starting with
+: Content added in source
4. Next Steps
Next steps:
1. Review the changes above
2. Update README_ko.md accordingly
3. Update frontmatter in README_ko.md
4. Verify: bun scripts/verify-readme-sync.ts --pre-commit
Provides actionable guidance for translators.
Common Workflows
Regular Translation Updates
-
Check for changes:
/translate --dry-run -
Review changes: Examine the diff preview
-
Update translation: Edit your translation file
-
Update hashes:
bun scripts/verify-readme-sync.ts --update-hashes
New Translation File Creation
If the target file doesn't exist yet:
-
Copy source:
cp README.md README_ko.md -
Translate: Edit README_ko.md
-
Update hashes:
bun scripts/verify-readme-sync.ts --update-hashes
Understanding Frontmatter
content_hash (Source File)
---
content_hash: a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12
---
Computed from the file body (excluding frontmatter). Changes when content changes.
translated_from_hash (Translation File)
---
translated_from_hash: a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12
---
Should match the source's content_hash. Indicates which version this translation is based on.
Troubleshooting
Source File Not Found
❌ Error: Source file not found: README.md
Solution: Check that the source file path is correct.
Hash Mismatch After Update
⚠️ Warning: Content hashes are out of sync!
Even after updating the translation:
Solution: Update the translated_from_hash field:
bun scripts/verify-readme-sync.ts --update-hashes
Verification Script Failure
❌ README sync check failed — commit blocked.
During git commit:
Solution:
- Update your translation
- Update hashes
- Commit again
Tips and Best Practices
Regular Checks
Run /translate --dry-run regularly to catch changes early.
Quality Maintenance
- Review diff carefully before updating
- Maintain consistent terminology
- Keep technical meaning accurate
- Apply the Korean Plain-Language Preference (
순우리말-first, percontext.mdLanguage Policy): in Korean output, prefer native Korean words over loanwords where a natural, widely-understood equivalent exists (e.g.만들기over크리에이션,알림over노티피케이션). Settled loanwords (컴퓨터,데이터,소프트웨어,파일) and established technical terms remain permitted — never sacrifice clarity or standard terminology for nativization.
Collaboration Workflow
- English author updates README.md
- Translator runs
/translate --dry-run - Translator updates README_ko.md
- Both run verification
Advanced Usage
Check Multiple Files
# Shell script example for multiple files
for file in README.md CONTRIBUTING.md; do
/translate "$file" "ko/$file"
done
Project-Level Files
/translate templates/common/README.md templates/common/README_ko.md
Related Scripts
- verify-readme-sync.ts: Validates README synchronization
- readme-lifecycle-audit.ts: Audits README lifecycle state
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.