view release on metacpan or  search on metacpan

README.gpt5-ZH.md  view on Meta::CPAN

# 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.02

# DESCRIPTION

**Greple** **xlate** 模块查找所需的文本块，并将其替换为翻译后的文本。主要引擎是 GPT-5.6 Terra（`llm/gpt5.pm`），它会调用 [llm](https://llm.datasette.io/) 命令；同时还包含 DeepL（`deepl.pm`）和基于旧ç‰...

翻译会按文件缓存，因此对未更改的文本重新运行命令不会产生任何成本。当文档被编辑时，只有已更改的段落会再次发送到 API；上下文感知引擎还会接收周围的翻译、变更周边的原始源文...

如果你想翻译以 Perl 的 pod 风格编写的文档中的普通文本块，请像这样将 **greple** 命令与 `--xlate-engine gpt5` 和 `perl` 模块一起使用：

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

在此命令中，模式字符串 `^([\w\pP].*\n)+` 表示以字母数字和标点符号开头的连续行。该命令会高亮显示将被翻译的区域。选项 **--all** 用于生成完整文本。

<div>
    <p>
    <img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/select-area.png">
    </p>
</div>

然后添加 `--xlate` 选项以翻译所选区域。接着，它会找到所需的部分并将其替换为翻译引擎的输出。

默认情况下，原文与译文会以与 [git(1)](http://man.he.net/man1/git) 兼容的“冲突标记”格式打印。使用 `ifdef` 格式，你可以轻松通过 [unifdef(1)](http://man.he.net/man1/unifdef) 命令获取所需部分。输出格å...

<div>
    <p>
    <img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/format-conflict.png">
    </p>
</div>

如果你想翻译整篇文本，使用 **--match-all** 选项。这是指定匹配整篇文本的模式 `(?s).+` 的快捷方式。

冲突标记格式的数据可用 [sdif](https://metacpan.org/pod/App%3A%3Asdif) 命令配合 `-V` 选项以并列样式查看。由于逐字符串比较没有意义，建议使用 `--no-cdif` 选项。如果不需要为文本着色，指定 `--no-te...

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

<div>
    <p>
    <img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/sdif-cm-view.png">
    </p>
</div>

# NORMALIZATION

处理按指定的单位进行，但对于多行非空文本的序列，会合并为一行。该操作按如下方式执行：

- 移除每行开头和结尾的空白。
- 如果一行以全角标点符号结尾，则与下一行连接。
- 如果一行以全角字符结尾且下一行以全角字符开头，则连接这些行。
- 如果行的结尾或开头不是全角字符，则在中间插入一个空格字符后再连接。

缓存数据基于规范化后的文本进行管理，因此即使进行了不影响规范化结果的修改，缓存的翻译数据仍然有效。

该规范化过程仅对第一个（第 0 个）以及偶数序号的模式执行。因此，如果指定了如下两个模式，则与第一个模式匹配的文本会在规范化后处理，与第二个模式匹配的文本则不执行规范化。

    greple -Mxlate -E normalized -E not-normalized

因此，对于需要将多行合并为一行来处理的文本，使用第一个模式；对于预格式化文本，使用第二个模式。如果第一个模式中没有可匹配的文本，则使用诸如 `(?!)` 之类不匹配任何内容的模å¼...

# MASKING

有时会有不想被翻译的文本部分。例如，Markdown 文件中的标签。DeepL 建议在这种情况下，将需要排除的文本部分转换为 XML 标签，进行翻译后再恢复。为支持此流程，可以指定从翻译中屏蔽çš...

    --xlate-setopt maskfile=MASKPATTERN

这将把文件的每一行 `MASKPATTERN` 解释为正则表达式，翻译与其匹配的字符串，并在处理后还原。以 `#` 开头的行将被忽略。

复杂的模式可以使用反斜杠转义换行写在多行上。

通过 **--xlate-mask** 选项可以查看文本经屏蔽转换后的样子。

屏蔽占位符是格式正确的自闭合 XML 标签，例如 `<m id="1" />`。基于 JSON çš„ LLM 引擎会在其输入数组中接收这些标签。对于 DeepL，包含标记标签的请求会被转义并封装在临时的 `<xlate>` 根标签中ï...

屏蔽可保护标记不被翻译。若要向翻译服务本身隐藏敏感字符串，请参见 ["ANONYMIZATION AND TEMPLATES"](#anonymization-and-templates)；两者可以一起使用。

此接口为实验性质，将来可能会改变。

# ANONYMIZATION AND TEMPLATES

敏感字符串可以在发送到翻译 API 之前被隐藏，并在输出中恢复。可使用三种匿名化规则来源：字典文件（**--xlate-anonymize**）、文档本身中的内联标记（**--xlate-anonymize-mark**）以及 YAML front mat...

对于表单类文档（季度报告等），请预先定义参与者，并在正文中引用它们：

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

每种语言只需使用 `--xlate-template` 翻译一次模板（当值保存在文件中时还需使用 `--xlate-frontmatter`），然后用 **pandoc-embedz** 独立模式渲染每个案例——外部配置中 `global:` 下的值完全不会到达ç...

    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

对于内联标记，提供宏定义配置可使同一个已翻译模板渲染为真实姓名或脱敏版本：

README.gpt5-ZH.md  view on Meta::CPAN

    在当前实现中，如果一行中的多个部分被翻译，它们会作为独立的行输出。

# 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](https://metacpan.org/pod/App%3A%3Adozo)处理，它也可以作为独立命令使用。`dozo`命令支持`.dozorc`配置文件以持久化容器设置。

此外，由于提供了适用于各种文档样式的 makefile，无需特殊指定即可翻译成其他语言。请使用`-M`选项。

你也可以将 Docker 和`make`选项组合使用，以便在 Docker 环境中运行`make`。

像`xlate -C`这样运行会启动一个挂载了当前工作 git 仓库的 shell。

请阅读["SEE ALSO"](#see-also)章节中的日文文章以了解详情。

# EMACS

加载仓库中包含的`xlate.el`文件，以便在 Emacs 编辑器中使用`xlate`命令。`xlate-region`函数会翻译给定区域。默认语言是`EN-US`，你可以通过带前缀参数调用来指定语言。

<div>
    <p>
    <img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/emacs.png">
    </p>
</div>

# ENVIRONMENT

- DEEPL\_AUTH\_KEY

    设置你的 DeepL 服务认证密钥。

- OPENAI\_API\_KEY

    OpenAI 认证密钥，由旧版 **gpty** 引擎使用。基于 `llm` 的 **gpt5** 引擎也会读取此变量，但使用 `llm keys set openai` 存储的密钥同样可用。

- GREPLE\_XLATE\_CACHE

    设置默认缓存策略（参见 ["CACHE OPTIONS"](#cache-options)）。

# INSTALL

## CPANMINUS

    $ cpanm App::Greple::xlate

## TOOLS

安装你所使用引擎的命令行工具：**gpt5** 引擎使用 `llm`，DeepL 使用 `deepl`，旧版 GPT 引擎使用 `gpty`。

[https://llm.datasette.io/](https://llm.datasette.io/)

[https://github.com/DeepLcom/deepl-python](https://github.com/DeepLcom/deepl-python)

[https://github.com/tecolicom/App-gpty](https://github.com/tecolicom/App-gpty)

# SEE ALSO

## MODULES

[App::Greple::xlate::llm](https://metacpan.org/pod/App%3A%3AGreple%3A%3Axlate%3A%3Allm), [App::Greple::xlate::deepl](https://metacpan.org/pod/App%3A%3AGreple%3A%3Axlate%3A%3Adeepl)

[App::dozo](https://metacpan.org/pod/App%3A%3Adozo) - 由 xlate 用于容器操作的通用 Docker 运行器

## RELATED MODULES

- [App::Greple](https://metacpan.org/pod/App%3A%3AGreple)

    关于目标文本模式的详细信息请参见**greple**手册。使用**--inside**、**--outside**、**--include**、**--exclude**选项限制匹配区域。

- [App::Greple::update](https://metacpan.org/pod/App%3A%3AGreple%3A%3Aupdate)

    你可以使用`-Mupdate`模块根据**greple**命令的结果来修改文件。

- [App::sdif](https://metacpan.org/pod/App%3A%3Asdif)

    使用**sdif**与**-V**选项并排显示冲突标记格式。

- [App::Greple::stripe](https://metacpan.org/pod/App%3A%3AGreple%3A%3Astripe)

    通过**--xlate-stripe**选项使用 Greple **stripe**模块。

## RESOURCES