/ 
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 front matter (--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. Четыре столбца зарезервированы для операции run‑in, поэтому каждая строка может содержать максимум 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)

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

--xlate-labor
--xlabor

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

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

Укажите целевой язык. Движки LLM принимают любое название языка или код, который понимает модель; оно подставляется в prompt перевода. Доступные языки можно получить командой 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+

Исходный и преобразованный текст выводятся, разделённые одной пустой строкой. Для 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

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

--xlate-context=text

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

--xlate-context-window=n

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

--xlate-cache-seed=file

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

--xlate-anonymize=file

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

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

или в простом построчном формате (category pattern, /.../ для regex). Каждый элемент заменяется тегом категории, таким как <person id=1 />; одна и та же строка всегда получает один и тот же тег, так что модель может отслеживать, кто есть кто. Неизвестные поля JSON игнорируются, поэтому генераторы (например, локальная LLM, извлекающая сущности) могут добавлять собственные аннотации. Категория lit зарезервирована. Локальные cache-файлы по-прежнему хранят восстановленный обычный текст: цель concealment — только передача в 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 ...

UTF-8 BOM в файле допускается. Значения в построчном формате front matter могут иметь завершающий комментарий только в отдельной строке, но не после значения.

--xlate-anonymize-mark[=regex]

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

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

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

--xlate-template[=regex]

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

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

--xlate-frontmatter

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

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

--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 для постоянных настроек контейнера.

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

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

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

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

EMACS

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

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, используемый 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.