AGENT SKILL

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

  1. Check for changes:

    /translate --dry-run
    
  2. Review changes: Examine the diff preview

  3. Update translation: Edit your translation file

  4. Update hashes:

    bun scripts/verify-readme-sync.ts --update-hashes
    

New Translation File Creation

If the target file doesn't exist yet:

  1. Copy source:

    cp README.md README_ko.md
    
  2. Translate: Edit README_ko.md

  3. 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:

  1. Update your translation
  2. Update hashes
  3. 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, per context.md Language 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

  1. English author updates README.md
  2. Translator runs /translate --dry-run
  3. Translator updates README_ko.md
  4. 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

5throck
5throck/ai-workspace-standards

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.

★ 25
5throck
5throck/ai-workspace-standards

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.

★ 25
5throck
5throck/ai-workspace-standards

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.

★ 25
5throck
5throck/ai-workspace-standards

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.

★ 25
5throck
5throck/ai-workspace-standards

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.

★ 25
5throck
5throck/ai-workspace-standards

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.

★ 25