/ 
App-Greple-xlate-2.00
⭐ Starred 0 / App::Greple::xlate

NAME

App::Greple::xlate - модуль поддержки перевода для greple

SYNOPSIS

greple -Mxlate --xlate-engine gpt5 --xlate pattern target-file

greple -Mxlate --xlate-engine deepl --xlate pattern target-file

VERSION

Version 2.00

DESCRIPTION

Greple xlate модуль находит нужные текстовые блоки и заменяет их переведённым текстом. Основным движком является GPT-5.5 (llm/gpt5.pm), который вызывает команду llm; также включены DeepL (deepl.pm) и устаревшие движки на основе gpty.

Переводы кэшируются по файлам, поэтому повторный запуск команды не требует затрат для неизменённого текста. При редактировании документа в API повторно отправляются только изменившиеся абзацы; контекстно-зависимый движок также получает окружающие переводы, исходный текст вокруг изменения и предыдущую версию отредактированного абзаца, благодаря чему новый перевод сохраняет устоявшуюся формулировку (см. --xlate-context-window). Конфиденциальные строки можно скрыть перед передачей (см. "ANONYMIZATION AND TEMPLATES").

Если вы хотите перевести обычные блоки текста в документе, написанном в стиле pod языка Perl, используйте команду greple с модулями --xlate-engine gpt5 и perl следующим образом:

greple -Mxlate --xlate-engine gpt5 -Mperl --pod --re '^([\w\pP].*\n)+' --all foo.pm

В этой команде шаблонная строка ^([\w\pP].*\n)+ означает последовательные строки, начинающиеся с букв алфавитно-цифрового ряда и знаков препинания. Эта команда показывает область, которую нужно перевести, выделенной. Опция --all используется для перевода всего текста.

Затем добавьте опцию --xlate для перевода выделенного фрагмента. После этого система найдёт нужные фрагменты и заменит их результатом работы механизма перевода.

По умолчанию оригинальный и транслированный текст печатается в формате "маркер конфликта", совместимом с git(1). Используя формат ifdef, можно легко получить нужную часть командой unifdef(1). Выходной формат может быть задан опцией --xlate-format.

Если требуется перевести весь текст, используйте опцию --match-all. Это сокращение для указания шаблона (?s).+, который соответствует всему тексту.

Данные в формате конфликтных маркеров можно просматривать в стиле "бок о бок" с помощью команды sdif с опцией -V. Поскольку сравнивать по каждой строке не имеет смысла, рекомендуется использовать опцию --no-cdif. Если вам не нужно окрашивать текст, укажите --no-textcolor (или --no-tc).

sdif -V --no-filename --no-tc --no-cdif data_shishin.deepl-EN-US.cm

NORMALIZATION

Обработка выполняется в заданных единицах, но в случае последовательности из нескольких строк непустого текста они преобразуются в одну строку. Эта операция выполняется следующим образом:

  • Удалите пробелы в начале и конце каждой строки.

  • Если строка заканчивается полноразмерным символом препинания, объедините ее со следующей строкой.

  • Если строка заканчивается символом полной ширины и следующая строка начинается символом полной ширины, объедините строки.

  • Если конец или начало строки не являются символами полной ширины, объедините их, вставив символ пробела.

Кэш-данные управляются на основе нормализованного текста, поэтому даже если будут внесены изменения, не влияющие на результаты нормализации, кэшированные данные перевода будут по-прежнему эффективны.

Этот процесс нормализации выполняется только для первого (0-го) и четного шаблона. Таким образом, если два шаблона указаны следующим образом, то текст, соответствующий первому шаблону, будет обработан после нормализации, а для текста, соответствующего второму шаблону, процесс нормализации не будет выполняться.

greple -Mxlate -E normalized -E not-normalized

Поэтому используйте первый шаблон для текста, который должен быть обработан путем объединения нескольких строк в одну, а второй - для предварительно отформатированного текста. Если в первом шаблоне нет текста для проверки, используйте шаблон, который ничему не соответствует, например (?!).

MASKING

Иногда встречаются части текста, которые не нужно переводить. Например, теги в файлах формата markdown. На сайте DeepL предлагается в таких случаях преобразовывать исключаемые части текста в XML-теги, переводить их, а затем восстанавливать после завершения перевода. Чтобы поддержать эту идею, можно указать части, которые нужно замаскировать от перевода.

--xlate-setopt maskfile=MASKPATTERN

Это будет интерпретировать каждую строку файла MASKPATTERN как регулярное выражение, переводить строку, соответствующую ему, и возвращать после обработки. Строки, начинающиеся с #, игнорируются.

Сложный шаблон можно записать на нескольких строках с использованием обратного слеша для экранирования символа новой строки.

Как текст преобразуется при маскировании, можно увидеть с помощью опции --xlate-mask.

Маскировка защищает разметку от перевода. Чтобы скрыть конфиденциальные строки от самого сервиса перевода, см. "ANONYMIZATION AND TEMPLATES"; оба метода можно использовать вместе.

Этот интерфейс является экспериментальным и может быть изменен в будущем.

ANONYMIZATION AND TEMPLATES

Конфиденциальные строки можно скрыть перед отправкой в API перевода и восстановить в выходных данных. Доступны три источника правил анонимизации: файл словаря (--xlate-anonymize), встроенные метки в самом документе (--xlate-anonymize-mark) и значения в предваряющей части YAML (--xlate-frontmatter). Каждая строка во время передачи заменяется тегом категории, например <person id=1 />. Скрытие распространяется только на передачу через API: в локальных файлах кэша хранится восстановленный обычный текст. Используйте --xlate-dryrun, чтобы проверить, что именно будет передано.

Для документов-шаблонов (квартальных отчётов и т. п.) заранее определите участники и ссылайтесь на них в тексте:

---
報告者: 山田太郎
発注会社: アクメ株式会社
---
本件について {{ 報告者 }} が調査を行った。

Переведите шаблон один раз на каждый язык с помощью --xlate-template (и --xlate-frontmatter, если значения хранятся в файле), затем отобразите каждый случай с помощью pandoc-embedz в автономном режиме — значения под global: во внешней конфигурации вообще не попадают в API перевода:

greple -Mxlate --xlate --xlate-engine=gpt5 --xlate-to=EN-US \
       --xlate-template= --xlate-format=xtxt \
       --match-paragraph --all --need=0 \
       report-template.md > report-template.EN.md
pandoc-embedz --standalone report-template.EN.md \
              -c case-123.yaml -o report-123.EN.md < /dev/null

Для встроенных меток предоставление конфигурации определения макроса позволяет одному и тому же переведённому шаблону отображать либо настоящие имена, либо отредактированную версию:

# macros.yaml           # macros-redacted.yaml
preamble: |             preamble: |
  {% macro person(name) %}{{ name }}{% endmacro %}
                          {% macro person(name) %}(関係者){% endmacro %}

Исключайте блоки embedz из перевода, если документ их содержит:

--exclude '^```embedz\n(?s:.*?)^```\n'

OPTIONS

--xlate
--xlate-color
--xlate-fold
--xlate-fold-width=n (Default: 70)

Запустите процесс перевода для каждой совпавшей области.

Без этой опции greple ведет себя как обычная команда поиска. Таким образом, вы можете проверить, какая часть файла будет подвергнута переводу, прежде чем вызывать фактическую работу.

Результат команды выводится в стандартный аут, поэтому при необходимости перенаправьте его в файл или воспользуйтесь модулем App::Greple::update.

Опция --xlate вызывает опцию --xlate-color с опцией --color=never.

С опцией --xlate-fold преобразованный текст сворачивается на указанную ширину. Ширина по умолчанию равна 70 и может быть задана опцией --xlate-fold-width. Для обкатки зарезервировано четыре колонки, поэтому в каждой строке может содержаться не более 74 символов.

--xlate-engine=engine

Указывает движок перевода, который будет использоваться.

На данный момент доступны следующие движки

  • gpt5: gpt-5.5 (via the llm command)

  • deepl: DeepL API (via the deepl command)

  • gpt3: gpt-3.5-turbo (legacy, via the gpty command)

  • gpt4o: gpt-4o-mini (legacy, via the gpty command)

Модули движка сначала ищутся в пространствах имён бэкенда (llm, затем gpty), а затем непосредственно под App::Greple::xlate. Таким образом, gpt5 загружает App::Greple::xlate::llm::gpt5, который вызывает команду llm, в то время как gpt4o переключается на App::Greple::xlate::gpty::gpt4o. Используйте --xlate-setopt backend=gpty, чтобы принудительно выбрать конкретный бэкенд.

--xlate-labor
--xlabor

Вместо того чтобы вызывать механизм перевода, вы должны работать на него. После подготовки текста для перевода он копируется в буфер обмена. Вы должны вставить их в форму, скопировать результат в буфер обмена и нажать кнопку return.

--xlate-to (Default: EN-US)

Укажите целевой язык. Движки LLM принимают любое название или код языка, который понимает модель; он интерполируется в запрос на перевод. Вы можете получить список доступных языков с помощью команды deepl languages при использовании движка DeepL.

--xlate-from (Default: ORIGINAL)

Метка, используемая для исходного текста в форматах вывода conflict, colon и ifdef. При использовании движка DeepL в качестве языка источника также передаётся значение, отличное от значения по умолчанию.

--xlate-format=format (Default: conflict)

Укажите формат вывода оригинального и переведенного текста.

Следующие форматы, кроме xtxt, предполагают, что переводимая часть представляет собой набор строк. На самом деле можно перевести только часть строки, но указание формата, отличного от xtxt, не даст значимых результатов.

conflict, cm

Оригинальный и преобразованный текст печатаются в формате git(1) маркеров конфликтов.

<<<<<<< ORIGINAL
original text
=======
translated Japanese text
>>>>>>> JA

Вы можете восстановить исходный файл следующей командой sed(1).

sed -e '/^<<<<<<< /d' -e '/^=======$/,/^>>>>>>> /d'
colon, :::::::

Оригинальный и переведенный текст выводятся в пользовательском стиле контейнера markdown.

::::::: ORIGINAL
original text
:::::::
::::::: JA
translated Japanese text
:::::::

Приведенный выше текст будет переведен в HTML следующим образом.

<div class="ORIGINAL">
original text
</div>
<div class="JA">
translated Japanese text
</div>

Количество двоеточий по умолчанию равно 7. Если вы укажете последовательность двоеточий, например :::::, то она будет использоваться вместо 7 двоеточий.

ifdef

Оригинальный и преобразованный текст печатаются в формате cpp(1) #ifdef.

#ifdef ORIGINAL
original text
#endif
#ifdef JA
translated Japanese text
#endif

Вы можете восстановить только японский текст командой unifdef:

unifdef -UORIGINAL -DJA foo.ja.pm
space
space+

Оригинальный и преобразованный текст выводятся на печать, разделенные одной пустой строкой. Для пробел+ после преобразованного текста также выводится новая строка.

xtxt

Если формат xtxt (переведенный текст) или неизвестен, печатается только переведенный текст.

--xlate-maxlen=chars (Default: 0)

Укажите максимальную длину текста, отправляемого в API за один раз. Значение по умолчанию 0 означает собственное ограничение движка: для бесплатной учетной записи DeepL оно составляет 128K для API (--xlate) и 5000 для интерфейса буфера обмена (--xlate-labor). Вы можете изменить эти значения, если используете сервис Pro.

--xlate-maxline=n (Default: 0)

Укажите максимальное количество строк текста, которое будет отправлено в API за один раз.

Установите значение 1, если вы хотите переводить по одной строке за раз. Этот параметр имеет приоритет перед параметром --xlate-maxlen.

--xlate-prompt=text

Укажите пользовательский запрос, который будет отправлен в движок перевода. Эта опция доступна для движков LLM (gpt3, gpt4o, gpt5), но не для DeepL. Вы можете настроить поведение перевода, предоставив конкретные инструкции модели ИИ. Если подсказка содержит %s, она будет заменена названием языка перевода.

--xlate-context=text

Укажите дополнительную контекстную информацию, которая будет отправлена механизму перевода. Этот параметр можно использовать несколько раз, чтобы указать несколько контекстных строк. Контекстная информация помогает механизму перевода понять фон и создать более точный перевод.

--xlate-context-window=n

(Context-aware engines only, e.g. gpt5 on the llm backend) Количество окружающих переведённых блоков, передаваемых в качестве контекста при повторном переводе изменённых блоков (по умолчанию 2). Контекст также включает исходный текст вокруг изменённого участка (заголовки, структуру списка, подписи) и, при наличии, предыдущую версию изменённого текста, восстановленную из кэша, чтобы сохранить неизменённые формулировки. Установите значение 0, чтобы полностью отключить контекстный перевод. Обратите внимание, что каждый измененный участок переводится в рамках отдельного вызова API, а контекст может увеличить системную подсказку примерно на 8000 символов, поэтому контекстный перевод требует дополнительных затрат в обмен на обеспечение согласованности.

--xlate-cache-seed=file

Инициализировать кэш нового документа на основе файла кэша другого документа. Полезно для периодических отчётов: инициализировать кэш нового выпуска на основе кэша предыдущего выпуска, чтобы неизменённые абзацы не переводились заново, а отредактированные абзацы сохраняли формулировки предыдущего выпуска. Исходные данные используются только в том случае, если целевой кэш пуст; в противном случае они игнорируются с выводом предупреждения. При использовании значения по умолчанию --xlate-cache=auto указание исходных данных также подразумевает создание файла кэша нового документа.

--xlate-anonymize=file

Анонимизировать конфиденциальные строки перед отправкой в API перевода и восстанавливать их в выходных данных. Файл словаря содержит по одной записи на каждый элемент: в формате JSON (каноническом, генерируемом машиной)

[ { "category": "person",  "text": "山田太郎" },
  { "category": "company", "regex": "アクメ(株式会社)?" } ]

или в простом строчном формате (category pattern, /.../ для регулярных выражений). Каждый элемент заменяется тегом категории, например <person id=1 />; одна и та же строка всегда получает один и тот же тег, чтобы модель могла отслеживать, что к чему. Неизвестные поля JSON игнорируются, поэтому генераторы (например, локальный LLM, извлекающий сущности) могут добавлять свои собственные аннотации. Категория lit зарезервирована. В локальных файлах кэша по-прежнему хранится восстановленный обычный текст: скрытие касается только передачи через API.

Словарь может быть сгенерирован внешним инструментом — например, локальной моделью, извлекающей конфиденциальные сущности:

llm -m <local-model> \
    -s 'Extract sensitive entities as a JSON array of objects
        with "category" and "text" fields.' \
    < report.md > report.anon.json
greple -Mxlate --xlate-anonymize=report.anon.json ...

Наличие BOM в формате UTF-8 в файле допускается. Значения, записанные в формате строки вступительной информации, могут сопровождаться комментарием только в отдельной строке, а не после самого значения.

--xlate-anonymize-mark[=regex]

Соберите записи об анонимизации из встроенных меток в самом документе. Пометьте первое вхождение как {{ person("山田太郎") }}, и каждое вхождение этой строки во всём документе будет анонимизировано. Сама метка остаётся в исходном тексте и в переводе, поэтому документ также можно обработать с помощью макропроцессора в стиле Jinja2 (определите макрос person для вывода или редактирования имени). Пользовательский тег regex должен содержать именованные перехваты (?<category>...) и (?<text>...).

Обратите внимание, что при использовании такого параметра с опциональным значением в качестве значения будет принят последующий аргумент файла: при использовании нотации по умолчанию запишите --xlate-anonymize-mark= (с последующим =).

Можно настроить альтернативные нотации, например --xlate-anonymize-mark='@@(?<category>[a-z][a-z0-9_]*):(?<text>[^\n]+?)@@' для меток в стиле @@person:NAME@@ или форму HTML-комментария, которая остаётся невидимой в отображаемом Markdown. Правила маркировки собираются по отдельному документу: строка, помеченная в одном входном файле, не скрывается в другом файле того же прогона (в отличие от значений вступительной части, которые накапливаются по всем файлам).

--xlate-template[=regex]

Рассматривайте выражения шаблонов (по умолчанию: Jinja2 {{ ... }}, {% ... %}, {# ... #}) как непрозрачные заполнители: дайте модели указание копировать их без изменений и проверяйте для каждого блока, что ответ содержит точно такие же выражения, причём каждое — ровно столько же раз. Их порядок может измениться, поскольку при переводе они могут быть переупорядочены в соответствии с порядком слов в языке перевода. Неверное выражение приводит к прерыванию прогона; кэш фиксируется и замораживается, поэтому ничего из того, за что было заплачено, не теряется.

Обратите внимание, что при использовании такого параметра с опциональным значением в качестве значения будет принят последующий аргумент файла: запишите --xlate-template= (с последующим =) при использовании нотации по умолчанию.

--xlate-frontmatter

Рассматривайте начальный блок --- ... --- как вступительную часть YAML: исключить его из перевода и из фрагментов контекста фазы 2, а также добавить его плоские значения key: value в правила анонимизации (категория var) в качестве меры предосторожности. При наличии нескольких входных файлов собранные значения суммируются (при этом предпочтение отдаётся более строгой анонимизации).

Всегда оставляйте пустую строку после закрывающего тега ---. При использовании шаблона сопоставления в стиле абзаца вступительная часть, непосредственно примыкающая к основному тексту, образует один перекрывающийся блок, который исключение не может подавить (в этом случае выводится предупреждение); значения по-прежнему анонимизируются, но сама вступительная часть будет отправлена на перевод.

--xlate-glossary=glossary

Укажите идентификатор глоссария, который будет использоваться при переводе. Этот параметр доступен только при использовании механизма DeepL. Идентификатор глоссария должен быть получен из учетной записи DeepL и обеспечивает последовательный перевод специфических терминов.

--xlate-dryrun

Не вызывайте API перевода; вместо этого отображайте через индикатор прогресса каждый полезный груз точно так, как он будет передан (после анонимизации и маскирования). Это полезно для проверки того, что покидает систему, и для оценки стоимости выполнения задания.

--[no-]xlate-progress (Default: True)

Результат перевода можно увидеть в режиме реального времени в выводе STDERR. Данные From отображаются в том виде, в котором они передаются, после анонимизации и маскирования.

--xlate-stripe

Используйте модуль App::Greple::stripe, чтобы показать совпадающие части в виде полосок зебры. Это удобно, когда совпадающие части соединены встык.

Цветовая палитра переключается в соответствии с цветом фона терминала. Если вы хотите указать его явно, можно использовать --xlate-stripe-light или --xlate-stripe-dark.

--xlate-mask

Выполните функцию маскирования и отобразите преобразованный текст как есть, без восстановления.

--match-all

Установите весь текст файла в качестве целевой области.

--lineify-cm
--lineify-colon

В случае форматов cm и colon вывод разбивается и форматируется построчно. Поэтому, если перевести только часть строки, ожидаемый результат не будет получен. Эти фильтры исправляют вывод, испорченный переводом части строки в обычный построчный вывод.

В текущей реализации, если переводится несколько частей строки, они выводятся как независимые строки.

CACHE OPTIONS

Модуль xlate может хранить кэшированный текст перевода для каждого файла и считывать его перед выполнением, чтобы исключить накладные расходы на запрос к серверу. При стратегии кэширования по умолчанию auto, он сохраняет данные кэша только тогда, когда файл кэша существует для целевого файла.

Используйте --xlate-cache=clear, чтобы запустить управление кэшем или очистить все существующие данные кэша. После выполнения этой опции будет создан новый файл кэша, если он не существует, а затем он будет автоматически поддерживаться.

--xlate-cache=strategy
auto (Default)

Сохранять файл кэша, если он существует.

create

Создать пустой файл кэша и выйти.

always, yes, 1

Сохранять кэш в любом случае, пока целевой файл является обычным файлом.

clear

Сначала очистите данные кэша.

never, no, 0

Никогда не использовать файл кэша, даже если он существует.

accumulate

По умолчанию неиспользуемые данные удаляются из файла кэша. Если вы не хотите удалять их и сохранять в файле, используйте accumulate.

--xlate-update

Эта опция заставляет обновлять файл кэша, даже если в этом нет необходимости.

COMMAND LINE INTERFACE

Вы можете легко использовать этот модуль из командной строки с помощью команды xlate, входящей в дистрибутив. Информацию об использовании см. на странице руководства xlate.

Команда xlate поддерживает длинные опции в стиле GNU, такие как --to-lang, --from-lang, --engine и --file. Используйте xlate -h, чтобы увидеть все доступные опции.

Команда xlate работает совместно со средой Docker, поэтому даже если у вас ничего не установлено, вы можете использовать ее, пока доступен Docker. Используйте опцию -D или -C.

Операции Docker выполняются командой App::dozo, которая также может использоваться как отдельная команда. Команда dozo поддерживает конфигурационный файл .dozorc для постоянных настроек контейнера.

Кроме того, поскольку в комплекте поставляются make-файлы для различных стилей документов, перевод на другие языки возможен без специальных уточнений. Используйте опцию -M.

Вы также можете комбинировать опции Docker и make, чтобы запустить make в среде Docker.

Выполнение xlate -C запустит оболочку с подключенным текущим рабочим git-репозиторием.

Подробности читайте в японской статье в разделе "SEE ALSO".

EMACS

Загрузите файл xlate.el, включенный в репозиторий, чтобы использовать команду xlate из редактора Emacs. Функция xlate-region переводит заданный регион. Язык по умолчанию - EN-US, и вы можете указать язык, вызывая ее с помощью аргумента prefix.

ENVIRONMENT

DEEPL_AUTH_KEY

Задайте ключ аутентификации для сервиса DeepL.

OPENAI_API_KEY

Ключ аутентификации OpenAI, используемый устаревшими движками gpty. Движок gpt5, основанный на llm, также считывает эту переменную, но ключи, хранящиеся с помощью llm keys set openai, тоже работают.

GREPLE_XLATE_CACHE

Установите стратегию кэширования по умолчанию (см. "CACHE OPTIONS").

INSTALL

CPANMINUS

$ cpanm App::Greple::xlate

TOOLS

Установите инструмент командной строки для используемого вами движка: llm для движка gpt5, deepl для DeepL, gpty для устаревших движков GPT.

https://llm.datasette.io/

https://github.com/DeepLcom/deepl-python

https://github.com/tecolicom/App-gpty

SEE ALSO

MODULES

App::Greple::xlate::llm, App::Greple::xlate::deepl

App::dozo - общий Docker runner, используемый xlate для операций с контейнерами.

  • App::Greple

    Подробную информацию о шаблоне целевого текста см. в руководстве greple. Используйте опции --inside, --outside, --include, --exclude для ограничения области совпадения.

  • App::Greple::update

    Вы можете использовать модуль -Mupdate для модификации файлов по результатам команды greple.

  • App::sdif

    Используйте sdif, чтобы показать формат маркера конфликта бок о бок с опцией -V.

  • App::Greple::stripe

    Использование модуля Greple stripe с помощью опции --xlate-stripe.

RESOURCES

ARTICLES

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright © 2023-2026 Kazumasa Utashiro.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.