/ 
App-Greple-xlate-0.99
River stage zero No dependents
/ xlate

NAME

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

SYNOPSIS

xlate [ options ] -t lang file [ greple options ]
    -h   help
    -v   show version
    -d   debug
    -n   dry-run
    -a   use API
    -c   just check translation area
    -r   refresh cache
    -u   force update cache
    -s   silent mode
    -e # translation engine (*deepl, gpt3, gpt4, gpt4o)
    -p # pattern to determine translation area
    -x # file containing mask patterns
    -w # wrap line by # width
    -o # output format (*xtxt, cm, ifdef, space, space+, colon)
    -f # from lang (ignored)
    -t # to lang (required, no default)
    -m # max length per API call
    -l # show library files (XLATE.mk, xlate.el)
    --   end of option
    N.B. default is marked as *

Make options
    -M   run make
    -n   dry-run

Docker options
    -D * run xlate on the container with the same parameters
    -C * execute following command on the container, or run shell
    -A * attach to the live container
    N.B. -D/-C/-A terminates option handling

    -G   mount git top-level directory
    -H   mount home directory
    -V # specify mount directory
    -U   do not mount
    -R   mount read-only
    -K   do not remove and keep live container
    -Q   quit and remove live container
    -E # specify environment variable to be inherited
    -I # docker image or version (default: tecolicom/xlate:version)

Control Files:
    *.LANG    translation languates
    *.FORMAT  translation foramt (xtxt, cm, ifdef, colon, space)
    *.ENGINE  translation engine (deepl, gpt3, gpt4, gpt4o)

VERSION

Version 0.99

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, gpt3, gpt4, gpt4o

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, providing a powerful and flexible environment for translation tasks. This approach combines the strengths of xlate's translation capabilities with Docker's containerization benefits.

Key Concepts

Containerized Environment

By running xlate in a Docker container, you ensure a consistent and isolated environment for all translation tasks. This eliminates issues related to system dependencies or conflicting software versions.

Integration with Make

The Docker functionality can be combined with xlate's make feature, allowing for complex, multi-file translation projects to be managed efficiently within a containerized environment. For example:

xlate -DM -t 'EN FR DE' project_files/*.docx

This command runs xlate in a Docker container, utilizing make to process multiple files with specified target languages.

Flexible Mount Options

xlate provides options to mount different directories, including Git repositories (-G) and read-only mounts (-R). This allows for flexible workflow integration while maintaining data security.

Environment Variable Handling

With the ability to pass specific environment variables into the container (-E), you can easily manage API keys and other configuration settings without modifying the container itself.

Make Support

xlate utilizes GNU Make for automating and managing translation tasks. This feature is particularly useful for handling translations of multiple files or 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

Show help message.

-v

Show version information.

-d

Enable debug mode.

-n

Perform a dry-run without making any changes.

-a

Use API for translation.

-c

Check translation area without performing translation.

-r

Refresh the translation cache.

-u

Force update of the translation cache.

-s

Run in silent mode.

-e engine

Specify the translation engine to use.

-p pattern

Specify a pattern to determine the translation area.

-x file

Specify a file containing mask patterns.

-w width

Wrap lines at the specified width.

-o format

Specify the output format.

-f lang

Specify the source language (currently ignored).

-t lang

Specify the target language (required).

-m length

Specify the maximum length per API call.

-l file

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

MAKE OPTIONS

-M

Run make.

-n

Dry run.

DOCKER OPTIONS

Docker feature is invoked by the -D, -C or -A option. Once any of these options appear, subsequent options are not interpreted, so it should always be the last of Docker related options.

-D

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

-C

Execute the following command on the Docker container, or run a shell if no command is provided.

-A

Attach to a running container. If the container does not exist, a new one is created, and if there is a stopped container, it is restarted before connecting.

Target container is distinguished by name. The default container name is xlate. The last portion of the Docker image to run is given as the name of the container. If a directory to mount is specified, the name of that directory is added after dot (.). For example, if you run ubuntu:latest image with mounting home directory (-H), the container name will be ubuntu.yourname.

Naturally, the other docker options only apply the first time the container is launched. Use the -Q option to remove the existing container before starting. The -QA option can be used to restart the container.

When running in a docker environment, the current directory is mounted by default. If another directory is specified to be mounted, such as the git top directory or the home directory, it will still be moved to the current location within that tree and executed.

-G

Mount git(1) top-level directory.

-H

Mount user's home directory. The environment variable HOME is set to the mount point.

-V directory

Specify directory to be mounted.

-U

Do not mount any directory.

-R

Mount directory as read-only.

-E name[=value]

Specify environment variable to be inherited in Docker. Repeatable.

-I image

Specify Docker image name. If it begins with a colon (:), it is treated as a version of the default image.

-K

Keep containers alive after execution. By default, container is automatically removed upon exit (--rm). This option disables that automatic deletion. This option works like option -C, but does not involve the container name.

-N

Specifies the name of the live container explicitly. Once you have created a container named xlate, you can connect to it with just the -C option.

-Q

Quit and remove the existing live container. If a container with the specified name (default is xlate) exists, it will be stopped and removed.

If specified as -QC, then a new container is launched after the existing container is removed.

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

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright © 2023-2024 Kazumasa Utashiro.

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