view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

        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("山田太郎") }}`

README.md  view on Meta::CPAN

    document: a string marked in one input file is not concealed in
    another file of the same run (unlike front matter values, which
    accumulate across files).

- **--xlate-template**\[=_regex_\]

    Treat template expressions (default: Jinja2 `{{ ... }}`,
    `{% ... %}`, `{# ... #}`) as opaque placeholders: instruct the
    model to copy them unchanged and verify, per block, that the response
    contains exactly the same expressions, each the same number of times.
    Their order may change, since translation legitimately reorders them
    to follow the target language word order.  A broken expression
    aborts the run; the cache is checkpointed and frozen, so nothing paid
    for is lost.

    Note that with an optional-value option like this, a following
    file argument would be taken as the value: write
    `--xlate-template=` (with a trailing `=`) when using the
    default notation.

- **--xlate-frontmatter**

    Treat a leading `---` ... `---` block as YAML front matter: exclude
    it from translation and from the phase-2 context slices, and add its
    flat `key: value` values to the anonymization rules (category
    `var`) as a safety net.  With multiple input files the collected
    values accumulate (erring on the side of concealment).

    Always leave a blank line after the closing `---`.  With a
    paragraph-style match pattern, front matter that runs directly into
    the body text forms one straddling block that the exclusion cannot
    suppress (a warning is printed in that case); the values are still
    anonymized, but the front matter itself would be sent for
    translation.

- **--xlate-glossary**=_glossary_

    Specify a glossary ID to be used for translation.  This option is only
    available when using the DeepL engine.  The glossary ID should be obtained
    from your DeepL account and ensures consistent translation of specific terms.

- **--xlate-dryrun**

    Do not call the translation API; instead show, through the progress
    display, each payload exactly as it would be transmitted (after
    anonymization and masking).  Useful for checking what leaves the
    machine and for estimating the cost of a run.

- **--**\[**no-**\]**xlate-progress** (Default: True)

    See the translation result in real time in the STDERR output.  The
    `From` payload is shown as transmitted, after anonymization and
    masking.

- **--xlate-stripe**

    Use [App::Greple::stripe](https://metacpan.org/pod/App%3A%3AGreple%3A%3Astripe) module to show the matched part by zebra
    striping fashion.  This is useful when the matched parts are connected
    back-to-back.

    The color palette is switched according to the background color of the
    terminal.  If you want to specify explicitly, you can use
    **--xlate-stripe-light** or **--xlate-stripe-dark**.

- **--xlate-mask**

    Perform masking function and display the converted text as is without
    restoration.

- **--match-all**

    Set the whole text of the file as a target area.

- **--lineify-cm**
- **--lineify-colon**

    In the case of the `cm` and `colon` formats, the output is split and
    formatted line by line.  Therefore, if only a portion of a line is to
    be translated, the expected result cannot be obtained.  These filters
    fix output that is corrupted by translating part of a line into normal
    line-by-line output.

    In the current implementation, if multiple parts of a line are
    translated, they are output as independent lines.

# CACHE OPTIONS

**xlate** module can store cached text of translation for each file and
read it before execution to eliminate the overhead of asking to
server.  With the default cache strategy `auto`, it maintains cache
data only when the cache file exists for target file.

Use **--xlate-cache=clear** to initiate cache management or to clean up
all existing cache data.  Once executed with this option, a new cache
file will be created if one does not exist and then automatically
maintained afterward.

- --xlate-cache=_strategy_
    - `auto` (Default)

        Maintain the cache file if it exists.

    - `create`

        Create empty cache file and exit.

    - `always`, `yes`, `1`

        Maintain cache anyway as far as the target is normal file.

    - `clear`

        Clear the cache data first.

    - `never`, `no`, `0`

        Never use cache file even if it exists.

    - `accumulate`

        By default behavior, unused data is removed from the cache file.  If