codex-translator

name	codex-translator
description	Translation using OpenAI Codex CLI (codex exec). PREFERRED for translation. Use when: (1) User says 'translate', 'codex translate', 'translation', or 'codex translator', (2) Translating between languages (Japanese, English, etc.), (3) Translating documentation, comments, or UI strings. Codex drafts, Claude Code reviews and writes. Falls back to Claude Code if codex unresponsive.
allowed-tools	["Bash(node *)","Bash(timeout *)","Bash(gtimeout *)"]

Codex Translator

Translation via the codex plugin companion script, reviewed and finalized by Claude Code.

Codex Plugin Companion Script

The codex plugin provides a companion script for running tasks. Resolve it dynamically:

CODEX_PLUGIN_ROOT=$(command ls -d "$HOME/.claude/plugins/cache/openai-codex/codex"/*/ 2>/dev/null | sort -V | tail -1)
CODEX_COMPANION="${CODEX_PLUGIN_ROOT}scripts/codex-companion.mjs"

If the file does not exist, report "Codex plugin not installed. Run /codex:setup first." and fall back to Claude Code translation.

Usage for translation tasks:

node "$CODEX_COMPANION" task "<translation prompt>"

The task command runs Codex in read-only mode by default (no --write flag).

Process

Step 0: Pre-flight Rate Limit Check

Before doing anything, check if Codex is currently rate-limited:

RATE_CHECK=$(node $HOME/.claude/scripts/codex-rate-limit.js check 2>&1)
RATE_EXIT=$?

If RATE_EXIT is non-zero (rate-limited), skip all codex steps and jump directly to the Fallback step. Do NOT report the rate limit to the user — silently fall back.

Step 1: Understand the Translation Task

• Source language and target language
• Source text (inline, file path, or selection)
• Context (technical docs, UI strings, blog post, etc.)
• Tone preferences (formal, casual, technical)

Step 2: Build Translation Prompt

Translate the following text from <source-lang> to <target-lang>.

Context: <what the text is for — technical documentation, UI, blog, etc.>
Tone: <formal/casual/technical>

Rules:
- Preserve technical terms and code references as-is
- Maintain formatting (markdown, HTML tags, etc.)
- Preserve line breaks and paragraph structure
- Use natural phrasing in the target language

Text to translate:
---
<source text>
---

If translating a file, include the file content in the prompt.

Step 3: Run Codex

LOGDIR=$(node $HOME/.claude/scripts/get-logdir.js)
mkdir -p "$LOGDIR"
DATETIME=$(date +%Y%m%d_%H%M%S)

# Resolve codex companion script
CODEX_PLUGIN_ROOT=$(command ls -d "$HOME/.claude/plugins/cache/openai-codex/codex"/*/ 2>/dev/null | sort -V | tail -1)
CODEX_COMPANION="${CODEX_PLUGIN_ROOT}scripts/codex-companion.mjs"

# Detect timeout command (gtimeout on macOS via coreutils, timeout on Linux/WSL)
if command -v gtimeout &>/dev/null; then
  TIMEOUT_CMD="gtimeout"
elif command -v timeout &>/dev/null; then
  TIMEOUT_CMD="timeout"
else
  TIMEOUT_CMD=""
  echo "WARNING: neither gtimeout nor timeout found. Running without timeout."
fi

${TIMEOUT_CMD:+$TIMEOUT_CMD} ${TIMEOUT_CMD:+1500} node "$CODEX_COMPANION" task \
  "<translation prompt>" \
  > "$LOGDIR/${DATETIME}-codex-translation-draft.md" \
  2>"$LOGDIR/${DATETIME}-codex-translation-draft-stderr.log"

Timeout: 25 minutes.

Step 4: Check for Rate Limiting

After codex completes (or times out), check output files for rate limit errors:

node $HOME/.claude/scripts/codex-rate-limit.js check-output \
  "$LOGDIR/${DATETIME}-codex-translation-draft.md" \
  "$LOGDIR/${DATETIME}-codex-translation-draft-stderr.log"

If exit code is non-zero (rate limit detected), jump to Fallback.

Step 5: Fallback — Opus

If codex times out, produces no output, or is rate-limited:

• Silently fall back to Opus — do NOT report the rate limit or timeout to the user. Do NOT pause the workflow.
• Spawn a text-fixer subagent (or general-purpose subagent) with model: opus to perform the translation. Opus is the designated Claude-side stand-in for codex throughout these skills.
• Continue the workflow as if the subagent translation was the original plan

Step 6: Review and Finalize

1. Read codex output from the log file
2. Review translation quality:

• Natural phrasing in target language
• Technical accuracy
• Formatting preservation
• No omissions or additions

3. Fix any issues
4. Write the final translated content to the target file via Claude Code

Important: Claude Code does all file writing. Codex only drafts.

Step 7: Report

Present the translation to the user. Include the draft log path.

Timeout Policy

• Timeout: 25 minutes (1500s)
• If codex times out: Silently fall back to Opus (subagent at model: opus)
• Codex runs read-only — cannot modify files

Important Notes

• Codex provides the initial translation draft
• Claude Code reviews for quality and handles file operations
• For large translations (entire files), read the file content and include it in the prompt
• Supports any language pair — specify source and target explicitly
• Silent fallback policy: If codex is rate-limited, timed out, or unavailable, silently fall back to a subagent at model: opus (text-fixer or general-purpose). NEVER pause the workflow, NEVER report the rate limit to the user, NEVER ask what to do. Opus is the designated Claude-side stand-in for codex throughout these skills