notion-translate-skill

name	notion-translate-skill
description	Translate text blocks in a Notion page to any target language. Fetches text content, translates via AI, then updates blocks in-place. Use when user wants to translate a Notion page, or mentions "translate notion page", "翻译Notion页面", "notion翻译".

Notion Page Translate

Translate all text blocks in a Notion page to a target language. Uses a two-step process: fetch texts, then update with translations.

Prerequisites

1. Notion API Key: Create an integration at https://notion.so/my-integrations
2. Store the key:

mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key

3. Share target page with your integration (click "..." → "Connect to" → your integration name)

First Time Setup

Dependencies are auto-installed when the script runs. No manual setup needed.

Agent Execution Instructions

CRITICAL: Follow this workflow for translation:

1. Determine this SKILL.md file's directory path as SKILL_DIR
2. Command pattern:

(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <args>)

Translation Workflow

Step 1: Fetch all text blocks from the page:

(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts fetch-texts <page_id_or_url>)

This outputs a JSON array like:

[
  { "block_id": "abc123", "block_type": "paragraph", "text": "Hello world" },
  { "block_id": "def456", "block_type": "heading_1", "text": "Introduction" }
]

Step 2: Translate the texts. As the AI agent, you should:

1. Parse the JSON output from Step 1
2. Translate the text field of each entry to the target language
3. Keep block_id and block_type unchanged
4. Save the translated entries to a temporary JSON file

Important translation rules:

• Translate only the text content, preserve block_id and block_type
• Maintain the original formatting intent (headings stay headings, etc.)
• Keep proper nouns, brand names, URLs, and code snippets untranslated
• Preserve emoji and special characters

Step 3: Update the page with translations:

(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts update-texts <page_id_or_url> /tmp/translations.json)

Complete Example

# 1. Fetch texts and save to file
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts fetch-texts https://notion.so/My-Page-abc123) > /tmp/source_texts.json

# 2. AI translates and saves to /tmp/translations.json

# 3. Update page
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts update-texts abc123 /tmp/translations.json)

Supported Block Types

The following text block types are translated:

• paragraph
• heading_1, heading_2, heading_3
• bulleted_list_item, numbered_list_item
• to_do
• toggle
• callout
• quote

Non-text blocks (images, embeds, code blocks, tables, etc.) are preserved as-is.

Options

Command	Description
fetch-texts <page_id_or_url>	Fetch all text blocks as JSON (to stdout)
update-texts <page_id_or_url> <file.json>	Update blocks with translated text

How It Works

1. Fetch: Get all blocks from the page via Notion API, recursively up to 3 levels
2. Filter: Extract only text-type blocks with non-empty content
3. Translate: AI translates the text (external step)
4. Update: PATCH each block with the translated rich_text content

Dependencies

• Node.js (script runs with tsx)
• Notion API key configured

(Other dependencies auto-install on first run.)