view release on metacpan or  search on metacpan

README.deepl-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`) 以及**gpty**基于旧版模型的å¼...

翻译结果按文件进行缓存，因此对于未更改的文本，重新运行命令无需额外成本。 当文档被编辑时，仅将更改过的段落再次发送至 API；基于上下文的引擎还会接收周围的翻译内容、更改处å‘...

若要翻译采用 Perl pod 风格编写的文档中的普通文本块，请像这样结合 `--xlate-engine gpt5` 和 `perl` 模块使用 **greple** 命令：

    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` 选项。如果不需要给文本着色，可指定 `-...

    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 前置信息值...

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

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

使用 `--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.deepl-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` man 页。

`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

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

[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** 选项查看 **stripe** 模块的使用情况。

## RESOURCES