/ 
App-Greple-xlate-2.01
⭐ Starred 0 / App::xlate

NAME

xlate - TRANSlate CLI front-end for App::Greple::xlate module

SYNOPSIS

xlate [ options ] -t LANG FILE [ greple options ]

Translation options:
  -h, --help        help
      --version     show version
  -d, --debug       debug mode (currently enables trace)
      --trace       trace mode
  -n, --dryrun      dry-run (-nn: preview transmission)
  -a, --api         use API (default; negate with --no-api)
  -c, --check       just check translation area
  -r, --refresh     refresh cache
  -u, --update      force update cache
  -s, --silent      silent mode
  -t, --to-lang=#   target language (required, no default)
  -b, --from-lang=# base language (informational)
  -e, --engine=#    translation engine (*gpt5, deepl, ...)
  -p, --pattern=#   pattern string to determine translation area
  -f, --file=#      pattern file to determine translation area
  -o, --format=#    output format (*xtxt, cm, ifdef, space, space+, colon)
  -x, --maskfile=#  file containing mask patterns
  -g, --glossary=#  glossary file
  --anonymize=#     anonymization dictionary file
  --mark[=#]        collect inline anonymization marks
  --template[=#]    protect template expressions
  --frontmatter     exclude/anonymize YAML front matter
  --seed=#          seed cache from another cache file
  --context=#       context blocks for re-translation
  -w, --wrap=#      wrap line by # width
  -m, --maxlen=#    max length per API call
  -l, --library=#   show library files (XLATE.mk, xlate.el)
  --                end of option
  N.B. default is marked as *

Make options:
  -M, --make        run make
  -n, --dryrun      dry-run (make -n)

Docker options:
  -D, --docker *    run xlate on the container with the same parameters
  -C, --command *   execute following command on the container, or run shell
  -L, --live *      use the live container
  N.B. These options terminate option handling

  -W, --mount-cwd    mount current working directory
  -H, --mount-home   mount home directory
  -V, --volume=#     specify mount directory
  -U, --unmount      do not mount
  -R, --mount-ro     mount read-only
  -B, --batch        run container in batch mode
  -N, --name=#       specify the name of live container
  -K, --kill         kill and remove live container
  -E, --env=#        specify an environment variable to be inherited
  -I, --image=#      docker image or version (default: tecolicom/xlate:version)
  -P, --port=#       port mapping
  -O, --other=#      additional docker option

Control Files:
  *.LANG    translation languages
  *.FORMAT  translation format (xtxt, cm, ifdef, colon, space)
  *.ENGINE  translation engine (gpt5, deepl, ...)
  *.ANONYMIZE  anonymization dictionary for the file

VERSION

Version 2.01

INCOMPATIBLE CHANGES IN 2.0

  • The default translation engine changed from deepl to gpt5. Cache file names include the engine name (FILE.xlate-gpt5-LANG.json), so running without -e deepl creates a new cache for existing DeepL-translated documents.

  • API translation is now the default. The clipboard-based manual translation mode requires --no-api (the former default); -a/--api remains valid as an explicit default.

DESCRIPTION

XLATE is a versatile command-line tool designed as a user-friendly frontend for the greple -Mxlate module, simplifying the process of multilingual automatic translation using various API services. It streamlines the interaction with the underlying module, making it easier for users to handle diverse translation needs across multiple file formats and languages.

A key feature of xlate is its seamless integration with Docker environments, allowing users to quickly set up and use the tool without complex environment configurations. This Docker support ensures consistency across different systems and simplifies deployment, benefiting both individual users and teams working on translation projects.

xlate supports various document formats, including .docx, .pptx, and .md files, and offers multiple output formats to suit different requirements. By combining Docker capabilities with built-in make functionality, xlate enables powerful automation of translation workflows. This combination facilitates efficient batch processing of multiple files, streamlined project management, and easy integration into continuous integration/continuous deployment (CI/CD) pipelines, significantly enhancing productivity in large-scale localization efforts.

Basic Usage

To translate a file, use the following command:

xlate -t <target_language> <file>

For example, to translate a file from English to Japanese:

xlate -t JA example.txt

Translation Engines

xlate supports multiple translation engines. Use the -e option to specify the engine:

xlate -e deepl -t JA example.txt

Available engines: gpt5, deepl, ...

Output Formats

Various output formats are supported. Use the -o option to specify the format:

xlate -o cm -t JA example.txt

Available formats: xtxt, cm, ifdef, space, space+, colon

Docker Support

xlate offers seamless integration with Docker through the dozo command. Use -D to run xlate in a container, or -C to run arbitrary commands.

xlate -D -t JA file.txt      # run xlate in container
xlate -C make                # run make in container
xlate -DM -t 'EN FR' *.docx  # combine with make

Docker options (-I, -E, -W, -H, -V, -U, -R, -B, -N, -K, -L, -P, -O) are passed to dozo. For details on live containers, container naming, and configuration, see App::dozo.

Note: The generic Docker runner functionality (-C, -L options) has been moved to the standalone App::dozo command. For running arbitrary commands or managing live containers, use dozo directly. These options in xlate are maintained for backward compatibility but may be deprecated in future versions.

Make Support

xlate utilizes GNU Make for automating and managing translation tasks. This feature is particularly useful for handling translations of multiple files or translations to different languages.

To use the make feature:

xlate -M [options] [target]

xlate provides a specialized Makefile (XLATE.mk) that defines translation tasks and rules. This file is located in the xlate library directory and is automatically used when the -M option is specified.

Example usage:

xlate -M -t 'EN FR DE' document.docx

This command will use make to translate document.docx to English, French, and German, following the rules defined in XLATE.mk.

The -n option can be used with -M for a dry-run, showing what actions would be taken without actually performing the translations:

xlate -M -n -t 'EN FR DE' document.docx

Users can customize the translation process using parameter files:

*.LANG:

Specifies target languages for a specific file

*.FORMAT:

Defines output formats for a specific file

*.ENGINE:

Selects the translation engine for a specific file

For more detailed information on the make functionality and available rules, refer to the XLATE.mk file in the xlate library directory.

OPTIONS

-h, --help

Show help message.

--version

Show version information.

-d, --debug

Enable debug mode. Currently this enables trace mode.

--trace

Enable trace mode (set -x).

-n, --dryrun

Given once, print the composed greple command line without executing it. Given twice (-nn), execute the command with --xlate-dryrun: no translation API is called, and each payload is shown exactly as it would be transmitted, after anonymization and masking. In make mode (-M), this option always means make -n.

-a, --api

Use the translation API. This is the default since 2.0; use --no-api to fall back to the clipboard-based manual translation (labor) mode. In make mode (-M), the clipboard mode is not available; XLATE_USEAPI is kept only for backward compatibility, since the API is used by default regardless of its value.

-c, --check

Check translation area without performing translation.

-r, --refresh

Refresh the translation cache.

-u, --update

Force update of the translation cache.

-s, --silent

Run in silent mode.

-t lang, --to-lang=lang

Specify the target language (required).

-b lang, --from-lang=lang

Specify the base language (optional).

-e engine, --engine=engine

Specify the translation engine to use. Default is gpt5.

-p pattern, --pattern=pattern

Specify a pattern to determine the translation area. See "NORMALIZATION" in App::Greple::xlate.

-f file, --file=file

Specify a file containing patterns to determine the translation area. See "NORMALIZATION" in App::Greple::xlate.

-o format, --format=format

Specify the output format.

-x file, --maskfile=file

Specify a file containing mask patterns. See "MASKING" in App::Greple::xlate.

-g file, --glossary=file

Specify a glossary file.

--anonymize=file

Anonymize sensitive strings before they are sent to the translation API using the dictionary file (JSON or line format), and restore them in the output. See "ANONYMIZATION AND TEMPLATES" in App::Greple::xlate for the dictionary format.

--mark[=regex]

Collect anonymization entries from inline marks in the document, such as {{ person("NAME") }}. An optional regex selects an alternative mark notation; it must contain (?<category>...) and (?<text>...) named captures.

--template[=regex]

Treat template expressions (default: Jinja2) as opaque placeholders: they are protected from translation and verified afterwards.

--frontmatter

Exclude a leading YAML front matter block from translation and add its values to the anonymization rules. Leave a blank line after the closing ---.

--seed=file

Initialize a new document's translation cache from another document's cache file. Useful for periodic reports.

--context=n

Number of surrounding translated blocks passed as context when re-translating changed blocks (default 2, 0 to disable).

-w width, --wrap=width

Wrap lines at the specified width.

-m length, --maxlen=length

Specify the maximum length per API call.

-l file, --library=file

Show library files (XLATE.mk, xlate.el).

MAKE OPTIONS

-M, --make

Run make.

-n, --dryrun

Dry-run (make -n).

DOCKER OPTIONS

-D, --docker

Run xlate on the Docker container with the rest of the parameters. Once this option appears, subsequent options are not interpreted by xlate, so it should always be the last of the xlate options.

The following options are specific to App::dozo and are passed through when invoking Docker features. These options are maintained for backward compatibility but may be removed in future versions. For direct container management, use the App::dozo command instead.

-C [ command ], --command

Execute command on the Docker container, or run shell if no command.

-L [ command ], --live

Use live (persistent) container. See App::dozo for details.

-W, --mount-cwd

Mount current working directory.

-H, --mount-home

Mount home directory.

-U, --unmount

Do not mount any directory.

-R, --mount-ro

Mount read-only.

-V from:to, --volume=from:to

Additional volume mount. Repeatable.

-E name[=value], --env=name[=value]

Environment variable to inherit. Repeatable.

-I image, --image=image

Docker image. Prefix with colon (:version) for default image version.

-B, --batch

Batch mode (non-interactive).

-N name, --name=name

Container name for live container.

-K, --kill

Kill and remove the live container.

-P port, --port=port

Port mapping (e.g., 8080:80). Repeatable.

-O option, --other=option

Additional docker option. Repeatable.

ENVIRONMENT

DEEPL_AUTH_KEY

DeepL API key.

OPENAI_API_KEY

OpenAI API key.

ANTHROPIC_API_KEY

Anthropic API key.

LLM_PERPLEXITY_KEY

Perplexity API key.

FILES

*.LANG

Specifies translation languages.

*.FORMAT

Specifies translation format.

*.ENGINE

Specifies translation engine.

*.ANONYMIZE

Anonymization dictionary applied to the file (used by the make workflow; takes precedence over XLATE_ANONYMIZE).

EXAMPLES

1. Translate a Word document to English:

xlate -DMa -t EN-US example.docx

2. Translate to multiple languages and formats:

xlate -M -o 'xtxt ifdef' -t 'EN-US KO ZH' example.docx

3. Run a command in Docker container:

xlate -C sdif -V --nocdif example.EN-US.cm

4. Translate without using API (via clipboard-based manual labor):

xlate --no-api -t JA README.md

5. Translate a report template whose actors are defined in YAML front matter, keeping template expressions intact and sending no real names to the API, then render each case with pandoc-embedz:

xlate -t EN-US --frontmatter --template 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

SEE ALSO

App::Greple::xlate

App::dozo - Generic Docker runner used by xlate for container operations

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright © 2023-2026 Kazumasa Utashiro.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.