translator

Files (4)

• SKILL.md
• anti-fabrication.md · references/
• i18n-de.md · references/
• terminology-glossary.md · references/

SKILL.md (first lines)

# Translator

Translate web content between locales. Every translation must read like it
was originally written in the target language while preserving exact file
structure.

## Project context

- **Framework**: {CONFIGURE: i18n framework}
- **Content pipeline**: {CONFIGURE: Content pipeline}
- **Locales**: {CONFIGURE: Supported locales}
- **Dictionaries**: {CONFIGURE: Dictionary file path pattern}
- **Content files**: {CONFIGURE: Content file path pattern}

---

## 1. JSON dictionary translation

### Structure rules

Dictionaries are nested JSON objects. Keys are typically camelCase.

```
{
  "section": {
    "subsection": {
      "label": "Translate this value",
      "heading": "And this one"
    }
  }
}
```

**Preserve exactly:**
- Every key name (never translate keys)
- Nesting structure and depth
- Array length and index ordering
- Object property ordering (match source file order)
- Value types (string stays string, array stays array)

**Translate:**
- All string leaf values that contain human-readable text

**Do NOT translate:**
- Keys (ever)
- URLs in values (e.g., `"href": "/audit"`, `"href": "https://..."`)
- Brand names (define in project context or terminology glossary)
- Statistical values that appear as strings (e.g., `"value": "44%"`)

**If the source has interpolation variables** (`{{variable}}` or `{variable}`),
preserve them exactly in the translated string. Do not translate variable names.

### Validation

After translating dictionary files:

```bash
python .claude/scripts/validate-json-structure.py <original.json> <translated.json>
```

For batch locale parity checks:

```bash
python .claude/scripts/dictionary-diff.py --source en --target de --dir dictionaries
```

---

## 2. MDX content translation

### Frontmatter rules

MDX files use YAML frontmatter. Fields fall into two categories:

**Translate these text fields:**

| Field | Notes |
|-------|-------|
| `title` | Optimize for target-language search intent (see section 3) |
| `description` | Optimize for target-language search intent |
| `summary` | Natural adaptation, not word-for-word |
| `tagline` | Short, punchy — adapt to target language rhythm |

**Do NOT translate metadata fields (copy byte-identical):**

Date fields, author, image paths, tags, status, technical metadata,
ordering fields, category slugs, URLs, and any field whose value is
a machine-readable identifier rather than human-readable text.

### Body rules

**Translate:**
- All prose paragraphs
- Heading text (preserve heading level: `##` stays `##`)
- Table cell content (preserve table structure)
- List item text
- Image alt text if present
- Link text (the visible part in `[text](url)`)

**Do NOT translate:**
- URLs in links: `[translated text](original-url-unchanged)`
- Code blocks (inline or fenced)
- HTML entities or tags if present
- Markdown syntax characters (`#`, `|`, `-`, `*`, `>`)

### Validation

```bash
python .claude/scripts/validate-mdx-structure.py <original.mdx> <translated.mdx>
```

---

## 3. SEO/GEO-aware translation

Do not mechanically translate keywords. Optimize for how the target audience
actually searches.

**Title and description optimization:**

From thesaifpasha/LGTM, MIT.

More from thesaifpasha/LGTM