App-Greple-xlate
view release on metacpan or search on metacpan
{% macro person(name) %}{{ name }}{% endmacro %}
{% macro person(name) %}(関係者){% endmacro %}
Exclude embedz blocks from translation when a document contains them:
--exclude '^```embedz\n(?s:.*?)^```\n'
# OPTIONS
- **--xlate**
- **--xlate-color**
- **--xlate-fold**
- **--xlate-fold-width**=_n_ (Default: 70)
Invoke the translation process for each matched area.
Without this option, **greple** behaves as a normal search command. So
you can check which part of the file will be subject of the
translation before invoking actual work.
Command result goes to standard out, so redirect to file if necessary,
or consider to use [App::Greple::update](https://metacpan.org/pod/App%3A%3AGreple%3A%3Aupdate) module.
Option **--xlate** calls **--xlate-color** option with **--color=never**
option.
With **--xlate-fold** option, converted text is folded by the specified
width. Default width is 70 and can be set by **--xlate-fold-width**
option. Four columns are reserved for run-in operation, so each line
could hold 74 characters at most.
- **--xlate-engine**=_engine_
Specifies the translation engine to be used.
At this time, the following engines are available
- **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)
Engine modules are searched in backend namespaces first (`llm`, then
`gpty`), then directly under `App::Greple::xlate`. So `gpt5` loads
`App::Greple::xlate::llm::gpt5` which calls the `llm` command, while
`gpt4o` falls back to `App::Greple::xlate::gpty::gpt4o`. Use
`--xlate-setopt backend=gpty` to force a specific backend.
- **--xlate-labor**
- **--xlabor**
Instead of calling translation engine, you are expected to work for.
After preparing text to be translated, they are copied to the
clipboard. You are expected to paste them to the form, copy the
result to the clipboard, and hit return.
- **--xlate-to** (Default: `EN-US`)
Specify the target language. LLM engines accept any language name
or code the model understands; it is interpolated into the
translation prompt. You can get available languages by `deepl
languages` command when using **DeepL** engine.
- **--xlate-from** (Default: `ORIGINAL`)
Label used for the original text in `conflict`, `colon` and
`ifdef` output formats. With the **DeepL** engine a non-default
value is also passed as the source language.
- **--xlate-format**=_format_ (Default: `conflict`)
Specify the output format for original and translated text.
The following formats other than `xtxt` assume that the part to be
translated is a collection of lines. In fact, it is possible to
translate only a portion of a line, but specifying a format other than
`xtxt` will not produce meaningful results.
- **conflict**, **cm**
Original and converted text are printed in [git(1)](http://man.he.net/man1/git) conflict marker
format.
<<<<<<< ORIGINAL
original text
=======
translated Japanese text
>>>>>>> JA
You can recover the original file by next [sed(1)](http://man.he.net/man1/sed) command.
sed -e '/^<<<<<<< /d' -e '/^=======$/,/^>>>>>>> /d'
- **colon**, _:::::::_
The original and translated text are output in a markdown's custom
container style.
::::::: ORIGINAL
original text
:::::::
::::::: JA
translated Japanese text
:::::::
Above text will be translated to the following in HTML.
<div class="ORIGINAL">
original text
</div>
<div class="JA">
translated Japanese text
</div>
Number of colon is 7 by default. If you specify colon sequence like
`:::::`, it is used instead of 7 colons.
- **ifdef**
Original and converted text are printed in [cpp(1)](http://man.he.net/man1/cpp) `#ifdef`
format.
#ifdef ORIGINAL
original text
#endif
#ifdef JA
translated Japanese text
#endif
You can retrieve only Japanese text by the **unifdef** command:
unifdef -UORIGINAL -DJA foo.ja.pm
- **space**
- **space+**
Original and converted text are printed separated by single blank
line. For `space+`, it also outputs a newline after the converted
text.
- **xtxt**
If the format is `xtxt` (translated text) or unkown, only translated
text is printed.
- **--xlate-maxlen**=_chars_ (Default: 0)
Specify the maximum length of text to be sent to the API at once.
The default value 0 means the engine's own limit: for the free DeepL
account service that is 128K for the API (**--xlate**) and 5000 for
the clipboard interface (**--xlate-labor**). You may be able to
change these value if you are using Pro service.
- **--xlate-maxline**=_n_ (Default: 0)
Specify the maximum lines of text to be sent to the API at once.
Set this value to 1 if you want to translate one line at a time. This
option takes precedence over the `--xlate-maxlen` option.
- **--xlate-prompt**=_text_
Specify a custom prompt to be sent to the translation engine. This
option is available for the LLM engines (`gpt3`, `gpt4o`, `gpt5`)
but not for DeepL. You can customize the translation behavior by
providing specific instructions to the AI model. If the prompt
contains `%s`, it will be replaced with the target language name.
- **--xlate-context**=_text_
Specify additional context information to be sent to the translation
engine. This option can be used multiple times to provide multiple
context strings. The context information helps the translation engine
understand the background and produce more accurate translations.
- **--xlate-context-window**=_n_
(Context-aware engines only, e.g. `gpt5` on the llm backend)
Number of surrounding translated blocks passed as reference context
when re-translating changed blocks (default 2). The context also
includes the raw source text around the changed region (headings,
list structure, captions) and, when available, the previous version
of the changed text recovered from the cache, so that unchanged
wording is preserved. Set to 0 to disable context-aware translation
entirely.
Note that each changed region is translated in its own API call and
the context can add up to about 8000 characters to the system
prompt, so context-aware translation trades some extra cost for
consistency.
- **--xlate-cache-seed**=_file_
Initialize a new document's cache from another document's cache
file. Useful for periodic reports: seed the new issue's cache with
the previous issue's, so unchanged paragraphs are not re-translated
and edited paragraphs keep the previous issue's wording. The seed
is used only when the target cache is empty; otherwise it is
ignored with a warning. With the default `--xlate-cache=auto`, specifying a seed also
implies creating the new document's cache file.
- **--xlate-anonymize**=_file_
Anonymize sensitive strings before they are sent to the translation
API, and restore them in the output. The dictionary file gives one
entry per item: in JSON (canonical, machine-generatable)
[ { "category": "person", "text": "山田太郎" },
{ "category": "company", "regex": "アクメ(æ ªå¼ä¼šç¤¾)?" } ]
or in a simple line format (`category pattern`, `/.../` for regex).
Each item is replaced by a category tag such as `<person id=1 />`;
the same string always gets the same tag, so the model can keep track
of who is who. Unknown JSON fields are ignored, so generators (e.g. a
local LLM extracting entities) may add their own annotations.
Category `lit` is reserved. Local cache files still store restored
plain text: the concealment target is API transmission only.
A dictionary can be generated by an external tool -- for example a
local model extracting sensitive entities:
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 ...
A UTF-8 BOM in the file is tolerated. Values in the front matter
line format may carry a trailing comment only on their own line, not
after the value.
- **--xlate-anonymize-mark**\[=_regex_\]
Collect anonymization entries from inline marks in the document
itself. Mark the first occurrence like `{{ person("山田太郎") }}`
and every occurrence of the string document-wide is anonymized. The
mark itself stays in the source and in the translation, so a document
can also be processed by a Jinja2-style macro processor (define the
`person` macro to print or redact the name). A custom _regex_ must
contain `(?<category>...)` and `(?<text>...)` named captures.
Note that with an optional-value option like this, a following
file argument would be taken as the value: write
`--xlate-anonymize-mark=` (with a trailing `=`) when using the
default notation.
Alternative notations can be configured, for example
`--xlate-anonymize-mark='@@(?<category>[a-z][a-z0-9_]*):(?<text>[^\n]+?)@@'`
for `@@person:NAME@@`-style marks, or an HTML-comment form that stays
( run in 1.087 second using v1.01-cache-2.11-cpan-6aa56a78535 )