Переводы и локализация: DeepL и Claude

Время: ~20 мин теории + 25 мин практики

Суть урока

Один текст — несколько рынков. Статья про стоимость жизни в Куэнке написана на русском. Через несколько минут и за небольшие деньги она существует на испанском для местного рынка и на английском для международных инвесторов, с SEO-метаданными (заголовком и описанием для поисковиков) под каждый язык. Это не дословный перевод, а локализация: правильные термины, понятные местному читателю примеры, нужный тон.

Те же приёмы работают и в быту: ответить клиенту на его языке, написать родственникам за границу, разобраться в письме от арендодателя или из школы. Одно остаётся работой человека: официальные документы, для которых нужен заверенный перевод (об этом ниже).

Без кода: перевод в обычном чате. Для повседневных задач хватает чата Claude. Открой его в браузере, вставь текст и добавь короткий запрос:

Переведи это сообщение на испанский для [кому: клиенту в Мексике, тёте в Аргентине]. Тон [тёплый и вежливый / деловой], простой разговорный язык. Имена, даты, адреса и цены оставь как есть. После перевода перечисли фразы, которые можно понять двояко. Вот текст: [вставь текст]

Если ты не знаешь язык перевода, попроси Claude перевести результат обратно на русский и сверь смысл. Всё действительно важное (деньги, здоровье, договор) перед отправкой покажи человеку, который владеет языком.

Часть урока начиная с раздела про DeepL MCP — для тех, кто уже работает в Claude Code и хочет переводить много текста автоматически. Остальные могут её пропустить.

🎨 Образ: Ты построил кирпичный дом. Красивый, прочный. Теперь хочешь продать его сразу в пяти кварталах, где говорят на разных языках. Раньше пришлось бы строить пять домов. Сейчас достаточно одного дома и умного переводчика, который знает, как говорят и что ценят в каждом квартале.

Ключевые концепции

• DeepL API — специализированный переводчик, сильный в европейских языках, включая испанский и португальский. Многим его переводы кажутся естественнее, чем у переводчиков общего назначения; сравни на своих текстах
• DeepL MCP — официальное подключение DeepL к Claude Code: перевод становится частью работы, а не отдельным шагом (MCP — стандартный способ подключать к Claude внешние сервисы)
• Конвейер локализации (в коде его называют i18n pipeline; i18n — принятое у разработчиков сокращение слова internationalization) — автоматическая цепочка: исходный текст → машинный перевод → культурная адаптация → SEO-метаданные
• Глоссарий — список терминов, которые нельзя переводить или нужно переводить строго одним способом
• Культурная адаптация — замена идиом, примеров и отсылок на понятные читателю в другой стране
• Метаданные под рынок — заголовок, описание и ключевые слова страницы для каждого языка и рынка
• DeepL или Claude напрямую — когда первый дешевле, а когда второй точнее

Теория

Сравнение инструментов: DeepL vs Google Translate vs Claude напрямую

Качество перевода в таблицу не внесено: независимого теста у нас нет, а результат зависит от пары языков и темы. Сравни инструменты на своих текстах. Актуальные цены и версии: Актуальное сейчас.

Вывод: DeepL — для перевода большого объёма однотипных текстов (карточки товаров, шаблоны писем, документы). Claude — для культурной адаптации, творческих и специальных текстов. Google Translate — запасной вариант для редких языков.

Без кода: обычный перевод в чате

Для большинства повседневных переводов никакой конвейер не нужен. Открой Claude в браузере, вставь текст и добавь короткую просьбу. Так переводят ответ клиенту, сообщение родственникам или письмо, которое нужно понять.

Переведи это сообщение на испанский для [кому: клиенту из Техаса, моей тёте в Мексике]. Сохрани тон [тёплый и вежливый / деловой], пиши простым разговорным испанским, а имена, даты, адреса и цены оставь точно как есть. После перевода перечисли фразы, которые можно понять двояко. Вот текст: [вставь текст]

Если ты не знаешь языка, на который переводишь, попроси Claude перевести его же результат обратно на русский, чтобы проверить смысл. Всё действительно важное (деньги, здоровье, договор) перед отправкой дай прочитать человеку, который знает этот язык.

Дальше в уроке — для тех, кто уже работает в Claude Code и хочет переводить много текстов по расписанию.

DeepL MCP: перевод внутри Claude Code

С этого раздела начинается часть для тех, кто строит: нужны Claude Code и терминал. У DeepL есть официальный MCP-сервер (пакет deepl-mcp-server, нужен Node.js 18 или новее). Перевод становится частью работы, не нужно переключаться между вкладками.

Настройка в файле .mcp.json:

{
  "mcpServers": {
    "deepl": {
      "command": "npx",
      "args": ["-y", "deepl-mcp-server"],
      "env": {
        "DEEPL_API_KEY": "${DEEPL_API_KEY}"
      }
    }
  }
}

Сам ключ в файл не вписывают: вместо ${DEEPL_API_KEY} Claude Code подставит значение переменной окружения. Её задают в терминале перед запуском Claude Code (команда есть в практике).

После подключения Claude использует DeepL в рамках одной сессии:

Переведи статью через DeepL на испанский,
затем адаптируй под аудиторию Эквадора.

Claude вызовет DeepL для перевода, потом сам займётся адаптацией, и всё это в одном разговоре.

Конвейер локализации: от одного текста к пяти рынкам

🎨 Образ: Мебельная фабрика. Один чертёж кресла — пять сборочных линий. Каждая выпускает кресло под свой рынок: другой цвет, другая обивка, другая высота. Суть одна, детали под рынок.

Схема конвейера:

[Исходный текст на русском]
        ↓
[DeepL API — быстрый машинный перевод с глоссарием]
        ↓
[Claude Sonnet — культурная адаптация и тон]
        ↓
[Claude Haiku — SEO-метаданные под каждый рынок]
        ↓
[Файлы: article.ru.md / article.es.md / article.en.md]
[Метаданные: article.es.meta.json / article.en.meta.json]

Полный код конвейера на Python:

import anthropic
import deepl
import json
import os
from pathlib import Path

deepl_client = deepl.Translator(os.environ["DEEPL_API_KEY"])
claude_client = anthropic.Anthropic()

# Глоссарий: термины, которые НЕ переводятся или переводятся строго одним способом.
# Слева термин на языке исходного текста (здесь русский), справа нужный перевод
GLOSSARY_TERMS = {
    "ES": {
        "Acme Realty": "Acme Realty",                 # бренд — не переводить
        "Acme AI": "Acme AI",                         # название сервиса — не переводить
        "квартира": "departamento",                   # в Эквадоре говорят "departamento"
        "агентство недвижимости": "inmobiliaria",     # принятый местный термин
    },
    "EN-US": {
        "Acme Realty": "Acme Realty",
        "Acme AI": "Acme AI",
    }
}

MARKET_CONTEXT = {
    "ecuador": (
        "Латиноамериканский рынок, Эквадор. "
        "Аудитория: русскоязычные эмигранты и местные покупатели недвижимости. "
        "Формальный, но дружелюбный тон. "
        "Акцент на стабильности и долгосрочной инвестиции. "
        "Эквадор использует доллар США — это важный аргумент."
    ),
    "us": (
        "Американский рынок. Аудитория: предприниматели и инвесторы. "
        "Прямой, конкретный тон. Акцент на окупаемости и цифрах. "
        "Избегай излишних эмоций — только факты."
    ),
    "spain": (
        "Испанский рынок. Более формальный тон, чем в Латинской Америке. "
        "Используй испанский язык Испании (не латиноамериканский). "
        "Аудитория: образованные городские жители."
    ),
}


def create_deepl_glossary(source_lang: str, target_lang: str) -> str | None:
    """Создаём глоссарий в DeepL для защиты терминов."""
    terms = GLOSSARY_TERMS.get(target_lang, {})
    if not terms:
        return None

    try:
        glossary = deepl_client.create_glossary(
            name=f"acme-{source_lang}-{target_lang}-{hash(str(terms)) % 10000}",
            source_lang=source_lang,
            target_lang=target_lang,
            entries=terms
        )
        return glossary.glossary_id
    except deepl.DeepLException:
        return None   # DeepL не создал глоссарий (например, не поддерживает эту пару языков) — продолжаем без него


def translate_with_deepl(text: str, target_lang: str,
                          source_lang: str = "RU",
                          glossary_id: str = None) -> str:
    """Быстрый машинный перевод с сохранением форматирования."""
    result = deepl_client.translate_text(
        text,
        source_lang=source_lang,
        target_lang=target_lang,
        glossary=glossary_id,
        preserve_formatting=True,
        tag_handling="html"   # сохраняем HTML-теги в тексте
    )
    return result.text


def adapt_culturally(translated_text: str, target_lang: str,
                     target_market: str, content_type: str = "marketing") -> str:
    """
    Claude адаптирует перевод культурно.
    Не переводит заново — улучшает естественность и заменяет
    неуместные идиомы и культурные отсылки.
    """
    context = MARKET_CONTEXT.get(target_market, "Международная аудитория.")

    prompt = f"""Ты эксперт по культурной адаптации текстов для рынка {target_market}.

ЗАДАЧА: Адаптируй текст для целевой аудитории.
НЕ переводи заново — текст уже переведён машинно.
Улучши естественность, замени неуместные идиомы,
адаптируй примеры и культурные отсылки.

КОНТЕКСТ РЫНКА: {context}
ТИП ТЕКСТА: {content_type}

СТРОГИЕ ПРАВИЛА:
- Бренды "Acme Realty" и "Acme AI" — НЕ менять
- Числа и статистику — НЕ менять
- Ключевые тезисы — НЕ менять, только форму подачи
- Язык вывода: {target_lang}

ТЕКСТ ДЛЯ АДАПТАЦИИ:
{translated_text}

Верни ТОЛЬКО адаптированный текст без пояснений."""

    message = claude_client.messages.create(
        model="claude-sonnet-5-5",   # актуальные модели: страница «Актуальное сейчас»
        max_tokens=16000,   # с запасом: в этот лимит входит и «размышление» модели
        messages=[{"role": "user", "content": prompt}]
    )
    # В ответе могут быть блоки «размышления»: берём только текст
    return "".join(block.text for block in message.content if block.type == "text")


def generate_seo_metadata(content: str, target_lang: str,
                           target_market: str) -> dict:
    """
    Claude Haiku генерирует SEO-метаданные под местный рынок.
    Дешевле Sonnet, для такой чёткой задачи достаточно.
    """
    prompt = f"""На основе этого текста сгенерируй SEO-метаданные для рынка {target_market}.

ТЕКСТ (первые 1500 символов):
{content[:1500]}

Верни JSON:
{{
  "title": "до 60 символов, с ключевым словом",
  "meta_description": "до 155 символов",
  "h1": "основной заголовок страницы",
  "keywords": ["слово1", "слово2", "слово3", "слово4", "слово5"],
  "og_title": "для Open Graph (до 70 символов)",
  "og_description": "для Open Graph (до 200 символов)"
}}

Язык: {target_lang}
Учитывай, что на самом деле ищут люди на рынке {target_market}.
Верни ТОЛЬКО JSON, без других слов."""

    message = claude_client.messages.create(
        model="claude-haiku-4-5",   # проверь, что модель ещё доступна в API
        max_tokens=512,
        messages=[{"role": "user", "content": prompt}]
    )
    text = "".join(block.text for block in message.content if block.type == "text")
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        return {"raw": text}


def run_translation_pipeline(source_file: Path, source_lang: str,
                              targets: list[dict]) -> dict:
    """
    Полный конвейер перевода одного файла на несколько языков.

    Параметр targets — список словарей:
    [
        {"lang": "ES", "market": "ecuador", "output": "article.es.md"},
        {"lang": "EN-US", "market": "us", "output": "article.en.md"},
    ]
    """
    source_text = source_file.read_text(encoding="utf-8")
    results = {}

    for target in targets:
        lang = target["lang"]
        market = target["market"]
        output_path = Path(target.get("output", f"output.{lang.lower()}.md"))

        print(f"  → {lang} для {market}...")

        # 1. Глоссарий
        glossary_id = create_deepl_glossary(source_lang, lang)

        # 2. Машинный перевод
        raw_translation = translate_with_deepl(
            source_text,
            target_lang=lang,
            source_lang=source_lang,
            glossary_id=glossary_id
        )

        # 3. Культурная адаптация
        adapted = adapt_culturally(
            raw_translation,
            target_lang=lang,
            target_market=market,
            content_type="real_estate_marketing"
        )

        # 4. SEO-метаданные
        seo_meta = generate_seo_metadata(adapted, lang, market)

        # 5. Сохраняем файлы (перевод DeepL до адаптации тоже: его удобно сравнить с итогом)
        output_path.write_text(adapted, encoding="utf-8")
        output_path.with_suffix(".deepl.md").write_text(raw_translation, encoding="utf-8")
        meta_path = output_path.with_suffix(".meta.json")
        meta_path.write_text(
            json.dumps(seo_meta, ensure_ascii=False, indent=2),
            encoding="utf-8"
        )

        results[lang] = {
            "content": str(output_path),
            "meta": str(meta_path),
            "chars": len(source_text),
            "market": market
        }
        print(f"  ✅ {lang} готов: {output_path}")

    return results


# Пример использования
if __name__ == "__main__":
    results = run_translation_pipeline(
        source_file=Path("article-ru.md"),
        source_lang="RU",
        targets=[
            {"lang": "ES", "market": "ecuador", "output": "article-es.md"},
            {"lang": "EN-US", "market": "us", "output": "article-en.md"},
        ]
    )

    print("\n📊 Результат:")
    for lang, info in results.items():
        print(f"  {lang}: {info['content']} + {info['meta']}")

Глоссарий: иммунная система бренда от неверного перевода

🎨 Образ: Юрист написал договор на английском, в нём есть термин escrow (деньги лежат у третьей стороны, пока сделка не закрыта). Переводчик пишет по-испански «depósito en garantía»: формально верно. Но клиент в Латинской Америке привык к слову «fideicomiso». Одно слово, и доверие к документу уже не то.

Категории терминов для глоссария:

Пример культурной адаптации: разница видна наглядно

Оригинал (на русском):

"Вложить деньги в квартиру — надёжно, как вклад в Сбербанке."

После DeepL (на испанском):

"Invertir dinero en un apartamento es tan confiable como un depósito en Sberbank."

Проблема: читатель в Латинской Америке не знает, что такое Сбербанк.

После Claude (культурная адаптация, Эквадор):

"Invertir en un departamento en Cuenca es tan sólido como tener dólares en el Banco del Pacífico — sin riesgo de devaluación."

Замена: незнакомый Сбербанк → знакомый Banco del Pacífico. Добавлена местная деталь: Эквадор использует доллар США, и это важный довод для местного рынка.

⚠️ Пример показывает, как перевод подстраивает отсылки, а не как писать настоящую рекламу. Недвижимость не бывает без риска, и сравнение с банковским вкладом во многих странах могут счесть вводящим в заблуждение обещанием. В настоящем тексте описывай объект и не обещай надёжность.

Пример из практики: Acme Realty, с русского на испанский и английский

Что проходит через конвейер:

1. Статьи блога — около 5 в месяц, примерно 1500 слов (10 000 знаков) каждая
2. Карточки объектов — описания квартир и домов на 3 языках
3. Рассылки по почте — еженедельный обзор на 3 языках
4. Метаданные страниц — заголовок, описание и ключевые слова для каждого языка
5. Шаблоны для WhatsApp и Telegram — приветственные сообщения и напоминания

Стоимость в месяц (считаем только статьи):

• Объём: ~100 000 знаков (5 статей × 2 языка перевода × 10 000 знаков)
• DeepL (первичный перевод): платишь по тарифу; при таком объёме сравни бесплатный уровень и платные тарифы на странице DeepL
• Claude (адаптация): по токенам. Код из урока адаптирует весь текст; чтобы тратить меньше, адаптируй только важные страницы
• Итого: обычно заметно меньше, чем перевод того же объёма у фрилансера. Ставки зависят от рынка и языка, посчитай для себя

Актуальные цены и версии: Актуальное сейчас.

Когда DeepL дешевле Claude, а когда наоборот

🎨 Образ: DeepL — автоматическая линия на заводе. Claude — мастер-ремесленник. Для серийных деталей нужна линия. Для штучных изделий нужен мастер. Умный завод использует обоих.

Простое правило: типовой однотипный текст → DeepL. Текст должен звучать так, будто его написал человек → Claude.

⚠️ Официальные документы остаются работой человека. Для иммиграционных анкет, судебных бумаг, свидетельств о рождении и браке, дипломов обычно нужен заверенный перевод: переводчик подписывает заявление, что перевод полный и точный. AI поможет понять, что написано в документе, и подготовить вопросы переводчику, но версию для подачи делает человек. Правила задаёт ведомство, суд или учебное заведение, которое просит перевод: сначала узнай его требования. И прежде чем вставлять в любой онлайн-сервис документ с номером паспорта, страхового свидетельства или банковского счёта, закрась эти номера.

Практика

Без кода. Переведи одно настоящее сообщение запросом из начала урока, попроси обратный перевод на русский и сверь смысл. Готово, когда обратный перевод совпадает с тем, что ты хотел сказать, а двусмысленные фразы из списка Claude исправлены. Шаги 1–4 ниже — для тех, кто строит: нужны Claude Code и терминал.

Шаг 1: Получи ключ DeepL API и настрой MCP (5 мин)

1. Зарегистрируйся на deepl.com/pro-api — для старта есть бесплатный уровень (объём и условия смотри на сайте DeepL)
2. Скопируй ключ API: он лежит в аккаунте DeepL, в разделе ключей (адрес deepl.com/your-account/keys)
3. Добавь сервер в .mcp.json (см. код из теории)
4. Задай ключ переменной окружения в том терминале, из которого запускаешь Claude Code: export DEEPL_API_KEY="твой-ключ" (в Windows PowerShell: $env:DEEPL_API_KEY="твой-ключ"). В сам файл .mcp.json ключ не вписывай
5. Запусти Claude Code заново, разреши сервер deepl, когда Claude Code об этом спросит, и попроси: "переведи 'Привет, мир' на испанский через DeepL"

Критерий успеха: Claude использует DeepL MCP и возвращает перевод.

Шаг 2: Создай глоссарий для своего проекта (5 мин)

pip install deepl anthropic

Сохрани код конвейера из теории в файл translation_pipeline.py. Свои термины выпиши в glossary.json, это твой рабочий список:

{
  "brand_names": ["Acme Realty", "Acme AI"],
  "do_not_translate": ["API", "MCP", "dashboard", "ROI", "CRM"],
  "market_specific": {
    "ecuador_es": {
      "квартира": "departamento",
      "недвижимость": "bienes raíces"
    }
  }
}

Затем перенеси термины в словарь GLOSSARY_TERMS в скрипте: функция create_deepl_glossary() берёт их оттуда. Проверишь на следующем шаге: в переводе название бренда не должно измениться.

Шаг 3: Запусти конвейер на настоящем тексте (10 мин)

1. Возьми любую статью или описание объекта (не меньше 500 слов) и сохрани рядом со скриптом как test-article.ru.md
2. Задай ключ Anthropic в том же терминале: export ANTHROPIC_API_KEY="...". Затем сохрани код ниже как run_test.py и запусти командой python run_test.py:

from pathlib import Path
from translation_pipeline import run_translation_pipeline

results = run_translation_pipeline(
    source_file=Path("test-article.ru.md"),
    source_lang="RU",
    targets=[
        {"lang": "ES", "market": "ecuador", "output": "test-article-es.md"},
    ]
)

3. Сравни три версии: оригинал, перевод DeepL (test-article-es.deepl.md) и текст после адаптации Claude (test-article-es.md)
4. Посмотри, что именно изменила культурная адаптация

Шаг 4: SEO-метаданные для каждого языка (5 мин)

Открой файл test-article-es.meta.json из предыдущего шага. Проверь:

• Title (заголовок страницы) — до 60 знаков, есть ключевое слово?
• Meta description (описание для поисковика) — до 155 знаков?
• Keywords (ключевые слова) — то, что ищут местные жители, а не дословный перевод?

Если что-то не так — поправь промпт в generate_seo_metadata().

Инструменты и ресурсы

• DeepL API — перевод для европейских языков, включая испанский и португальский; есть бесплатный уровень
• DeepL MCP — официальное подключение к Claude Code
• python-deepl — официальная библиотека DeepL для Python
• Google Cloud Translation — очень много языков, подходит для редких
• Claude Sonnet — культурная адаптация и творческие тексты
• Crowdin — командная работа с переводами и память переводов, тарифы на сайте
• Lokalise — локализация онлайн-сервисов, тарифы на сайте
• i18next — библиотека локализации для приложений на JavaScript и React, бесплатно

Набор для малого бизнеса: бесплатный уровень DeepL → платный тариф при росте объёма + Claude для адаптации + скрипт на Python из этого урока.

Ключевые выводы

Машинный перевод переводит слова. Claude переводит смысл. DeepL делает первый шаг быстро и дёшево, Claude вторым шагом доводит текст до естественного звучания.

Глоссарий — иммунная система бренда в переводах. Один неверный перевод названия продукта или юридического термина может подорвать доверие целого рынка.

Токены и тариф DeepL вместо оплаты каждого перевода у фрилансера — это не только экономия, но и другой способ работы. Важные тексты всё равно показывай человеку, который владеет языком.

Официальные документы — исключение: когда ведомство или суд просит заверенный перевод, его делает переводчик-человек.

Следующий урок

→ Картинки с помощью AI — начинаем модуль про картинки, видео и музыку: какой генератор изображений взять под задачу

В библиотеке, по желанию: AI в мессенджерах — Telegram, Slack, WhatsApp и Microsoft Teams: боты, которые отвечают клиентам, присылают уведомления о сделках и управляют доступом к закрытым чатам.