view release on metacpan or  search on metacpan

README.gpt5-JA.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/) コã...

翻訳はファイルごとにキャッシュされるため、変更されていないテキストについてはコマンドを再実行してもコストはかかりません。文書が編集された場合、変更された段落だけが再度 ...

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` オプションを付けてサイドバイサイド表示することができます。文字列単位で比較しても意味ã...

    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

処理は指定した単位で行われますが、空でない複数行の連続したテキストの場合は、まとめて 1 行に変換されます。この操作は次のように行われます:

- 各行の先頭と末尾の空白を削除します。
- 行が全角の句読点で終わる場合は、次の行と連結します。
- 行が全角文字で終わり、次の行が全角文字で始まる場合は、行を連結します。
- 行末または行頭のいずれかが全角文字でない場合は、スペース文字を挿入して連結します。

キャッシュデータは正規化後のテキストに基づいて管理されるため、正規化結果に影響しない変更が行われても、キャッシュされた翻訳データは引き続き有効です。

この正規化処理は最初（0 番目）および偶数番目のパターンに対してのみ行われます。したがって、次のように 2 つのパターンが指定された場合、最初のパターンに一致するテキストはæ­...

    greple -Mxlate -E normalized -E not-normalized

したがって、複数行を 1 行にまとめて処理するテキストには最初のパターンを使用し、整形済みテキストには 2 番目のパターンを使用してください。最初のパターンに一致するテキストã...

# MASKING

ときどき、翻訳したくないテキストの一部があります。たとえば、Markdown ファイル内のタグなどです。DeepL は、そのような場合には除外したいテキスト部分を XML タグに変換してから翻è¨...

    --xlate-setopt maskfile=MASKPATTERN

これは、ファイルの各行を`MASKPATTERN`として正規表現として解釈し、それにマッチする文字列を翻訳して処理後に元に戻します。`#`で始まる行は無視されます。

複雑なパターンは、バックスラッシュで改行をエスケープして複数行に記述できます。

マスキングによってテキストがどのように変換されるかは、**--xlate-mask** オプションで確認できます。

マスク用プレースホルダーは、`<m id="1" />` のような整形式の自己終了 XML タグです。JSON ベースの LLM エンジンは、入力配列内でこれらのタグを受け取ります。DeepL では、マーカータグをå...

マスキングはマークアップが翻訳されないように保護します。翻訳サービス自体から機密文字列を隠蔽するには、["ANONYMIZATION AND TEMPLATES"](#anonymization-and-templates)を参照してください。両方...

このインターフェイスは実験的で、将来変更される可能性があります。

# ANONYMIZATION AND TEMPLATES

機密性の高い文字列は、翻訳 API に送信される前に隠蔽し、出力で復元できます。匿名化ルールのソースは 3 種類あります: 辞書ファイル（**--xlate-anonymize**）、文書自体のインラインマー...

フォーム文書（四半期報告書など）では、アクターを最初に定義し、本文で参照します:

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

言語ごとにテンプレートを一度、`--xlate-template`（値をファイル内に保持する場合は `--xlate-frontmatter` も）で翻訳し、その後 **pandoc-embedz** スタンドアロンモードで各ケースをレンダリングã...

    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-JA.md  view on Meta::CPAN

    現在の実装では、1行の複数箇所が翻訳された場合、それらは独立した行として出力されます。

# CACHE OPTIONS

**xlate** モジュールは、ファイルごとに翻訳のキャッシュテキストを保存し、実行前に読み込んでサーバーへの問い合わせのオーバーヘッドを排除できます。デフォルトのキャッシュ戦略...

**--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` コマンドは、`--to-lang`、`--from-lang`、`--engine`、`--file` などの GNU 形式のロングオプションをサポートします。`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リポジトリをマウントしたシェルが起動します。

詳細は["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

    レガシー**gpty**エンジンで使用されるOpenAIの認証キー。`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)

    Greple **stripe**モジュールは**--xlate-stripe**オプションで使用します。

## RESOURCES