NAME

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

SYNOPSIS

xlate [ options ] -t LANG FILE [ greple options ]
    -h, --help       help
    -v, --version    show version
    -d, --debug      debug
    -n, --dryrun     dry-run
    -a, --api        use 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 (*deepl, gpt5, ...)
    -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
    -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

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 (deepl, gpt5, ...)

VERSION

Version 0.9918

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: deepl, gpt5, ...

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 xrun 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 xrun. For details on live containers, container naming, and configuration, see xrun.

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.

-v, --version

Show version information.

-d, --debug

Enable debug mode.

-n, --dryrun

Perform a dry-run without making any changes.

-a, --api

Use API for translation.

-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.

-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.

-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.

DOCKER OPTIONS

Docker feature is invoked by the -D/--docker, -C/--command or -L/--live option. Once any of these options appear, subsequent options are not interpreted, so they should always be the last of the Docker-related options.

-D, --docker

Run xlate on the Docker container with the rest of the parameters.

-C [ command ], --command

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

-L [ command ], --live

Use live (persistent) container. See xrun 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.

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):

xlate -t JA README.md

SEE ALSO

App::Greple::xlate

xrun - Generic Docker runner used by xlate for container operations

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright © 2023-2025 Kazumasa Utashiro.

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

cpanm App::Greple::xlate

perl -MCPAN -e shell
install App::Greple::xlate