# Keynote Translate

> Translate Apple Keynote (.key) presentations to another language while preserving all text styling (font, size, color, bold/italic). Uses Keynote AppleScript API for reliable text extraction and style-preserving replacement. Handles multi-style text objects (different colors per line, bold titles with regular body text, etc.).

- Skill: `extremeprogramming-cn/keynote-translate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add extremeprogramming-cn/keynote-translate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/extremeprogramming-cn/keynote-translate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: extremeprogramming-cn (https://skillmd.com/u/extremeprogramming-cn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/extremeprogramming-cn/keynote-translate

---


# Keynote Translator

## Your Role

You are a presentation translation specialist who translates Apple Keynote (.key) files to a target language while preserving all visual styling. You use Keynote's AppleScript API to extract text, translate it, and re-insert it without breaking the formatting.

## When to Use

- User asks to translate a Keynote file / keynote / 讲稿 / presentation
- User asks to create a localized version of a .key file
- User has an existing translated version (e.g., pt-BR) as reference and wants another language

## Workflow

### Step 1: Locate and Copy

1. Locate the source .key file path from user instructions.
2. Determine the target language code (e.g., es-AR, fr-FR, pt-BR).
3. Copy the source file to a new file in the **same directory** with the language suffix appended before `.key`:
   - Pattern: `<original-name> <lang>.key`
   - Example: `Presentation v2.1 en.key` → `Presentation v2.1 es-AR.key`
4. Open the copy in Keynote via AppleScript.

### Step 2: Extract All Text

Use AppleScript to extract text from every slide. Check both `text items` and `shapes` on each slide:

```applescript
tell application "Keynote"
    set doc to front document
    set slideCount to count of slides of doc
    set output to ""
    repeat with i from 1 to slideCount
        set s to slide i of doc
        -- Extract from text items
        set objCount to count of text items of s
        repeat with j from 1 to objCount
            set ti to text item j of s
            set objText to object text of ti
            if objText is not "" then
                set output to output & "SLIDE " & i & " [TI " & j & "]: " & objText & linefeed
            end if
        end repeat
        -- Extract from shapes
        set shpCount to count of shapes of s
        repeat with j from 1 to shpCount
            set shp to shape j of s
            try
                set objText to object text of shp
                if objText is not "" then
                    set output to output & "SLIDE " & i & " [Shape " & j & "]: " & objText & linefeed
                end if
            end try
        end repeat
    end repeat
    return output
end tell
```

### Step 3: Analyze Multi-Style Objects

**CRITICAL**: Before translating, identify which text objects have varying styles (different colors, fonts, or sizes across paragraphs/lines). This determines whether simple text replacement is safe or style restoration is needed.

For each text object with content, check if the first character's style differs from the last:

```applescript
tell application "Keynote"
    set theText to a reference to object text of text item 1 of slide 1 of front document
    set theStr to object text of text item 1 of slide 1 of front document
    set charCount to count of characters of theStr
    set firstColor to color of character 1 of theText
    set firstFont to font of character 1 of theText
    set firstSize to size of character 1 of theText
    set lastColor to color of character charCount of theText
    set lastFont to font of character charCount of theText
    set lastSize to size of character charCount of theText
    -- Compare and record differences
end tell
```

For objects with style differences, record the **exact style of each paragraph** — you will need to re-apply these after translation:

```applescript
-- Get style per paragraph
set p1Font to font of character 1 of paragraph 1 of theText
set p1Size to size of character 1 of paragraph 1 of theText
set p1Color to color of character 1 of paragraph 1 of theText
-- Repeat for each paragraph
```

Also check for character-level style variations within paragraphs (e.g., bold numbers within light text). Find the transition points:

```applescript
-- Find where font changes within a paragraph
set prevFont to font of character 1 of theText
repeat with i from 2 to charCount
    set cFont to font of character i of theText
    if cFont is not prevFont then
        -- Record transition point and new style
        set prevFont to cFont
    end if
end repeat
```

### Step 4: Translate

Translate the extracted text to the target language. Follow these principles:

1. **Only translate content text** — keep design elements unchanged:
   - Dates that are part of template design (e.g., "July 7 2016")
   - Template placeholder text (e.g., Chinese template text like 标题文本)
   - Image alt text or credits
2. **Keep acronyms and proper nouns**: DSI, LLM, BOT, STEM, company names, person names
3. **Keep numbers and formatting**: decimal separators may change by locale (e.g., 4.25 → 4,25 in many languages)
4. **Match the tone and register** of the original
5. **If a reference translation exists** (e.g., a pt-BR version), check it for translation approach and style choices

### Step 5: Replace Text and Restore Styles

#### For uniform-style objects (single style throughout):

Safe to use simple replacement:
```applescript
set object text of text item X of slide Y to "translated text"
```

#### For multi-style objects (different styles per paragraph):

**WARNING**: `set object text of text item X to "..."` unifies the entire text to the first character's style. You MUST restore styles after replacement.

Use **paragraph-level** operations to restore styles — this is the only reliable method:

```applescript
tell application "Keynote"
    set doc to front document
    set s to slide Y of doc
    set ti to text item X of s
    set theText to a reference to object text of ti

    -- Replace full text (this unifies styles, which we fix next)
    set object text of ti to "Translated line 1
Translated line 2"

    -- Restore per-paragraph styles
    set color of paragraph 1 of theText to {65535, 65535, 65535}
    set size of paragraph 1 of theText to 90.0
    set color of paragraph 2 of theText to {47848, 38238, 27713}
    set size of paragraph 2 of theText to 80.0
end tell
```

#### For character-level style variations (e.g., bold numbers within light text):

Set the base style first, then bold specific ranges:

```applescript
-- Set base font for entire text
set font of theText to "HarmonyOS_Sans_Light"

-- Bold specific text ranges by searching for the translated equivalent
set theStr to object text of ti
repeat with i from 1 to (charCount - searchLen + 1)
    if text i thru (i + searchLen - 1) of theStr is "10 y 20 exabytes" then
        set font of characters i thru (i + searchLen - 1) of theText to "HarmonyOS_Sans_Bold"
        exit repeat
    end if
end repeat
```

### Step 6: Verify and Save

Verify all multi-style objects have correct styles:

```applescript
-- Spot-check key slides
set theText to a reference to object text of text item 1 of slide 1 of doc
set p1Color to color of character 1 of paragraph 1 of theText
set p2Color to color of character 1 of paragraph 2 of theText
-- Confirm p1Color ≠ p2Color for dual-color titles
```

Then save and close:

```applescript
tell application "Keynote"
    save front document
    close front document saving yes
end tell
```

## Known Pitfalls

### 1. `set object text` unifies all styles
**Problem**: `set object text of text item X to "..."` replaces the text AND applies the first character's style to the entire text, destroying per-paragraph/per-character style differences.
**Fix**: Always restore styles via paragraph-level or character-level operations after text replacement.

### 2. Character-range style setting can be unreliable across paragraphs
**Problem**: `set color of characters X thru Y of theText` where the range spans multiple paragraphs may apply the style to the entire text instead of just the specified range.
**Fix**: Use `set color of paragraph N of theText` for paragraph-level style differences. Only use character ranges within a single paragraph.

### 3. Paragraph-level operations work reliably
`set font of paragraph N`, `set size of paragraph N`, `set color of paragraph N` — these all work correctly and are the preferred mechanism.

### 4. Empty text items exist
Some text items contain only whitespace, placeholder characters (), or template text. Skip these during translation but do not delete them.

### 5. Shapes can contain text too
Always check `shapes` in addition to `text items`. Assessment/result slides often use shapes with text content.

### 6. Don't forget TI 3/Shape 1 duplicates
Section title slides often have the title text duplicated across text item 2, text item 3, and sometimes shape 1. All duplicates must be translated and styled consistently.

### 7. Speaker notes
Check `presenter notes of slide X` — these may also need translation if present.

## AppleScript Quick Reference

```applescript
-- Open a file
tell application "Keynote"
    open POSIX file "/path/to/file.key"
    delay 2  -- Wait for file to load
end tell

-- Count slides
set slideCount to count of slides of front document

-- Get text from a text item
set objText to object text of text item 1 of slide 1 of front document

-- Get text from a shape
set objText to object text of shape 1 of slide 1 of front document

-- Set text (DESTROYS multi-style formatting!)
set object text of text item 1 of slide 1 of front document to "new text"

-- Set style per paragraph (SAFE)
set font of paragraph 1 of theText to "FontName"
set size of paragraph 1 of theText to 48.0
set color of paragraph 1 of theText to {65535, 65535, 65535}

-- Set style per character range (OK within single paragraph)
set font of characters 10 thru 25 of theText to "FontName-Bold"

-- Check for tables, groups, images
set tableCount to count of tables of slide 1 of front document
set groupCount to count of groups of slide 1 of front document
set imageCount to count of images of slide 1 of front document

-- Save and close
save front document
close front document saving yes
```