| 1 | package App::xlate; | ||
| 2 | |||
| 3 | our $VERSION = "2.03"; | ||
| 4 | |||
| 5 | 1; | ||
| 6 | =encoding utf-8 | ||
| 7 | |||
| 8 | =head1 NAME | ||
| 9 | |||
| 10 | xlate - TRANSlate CLI front-end for App::Greple::xlate module | ||
| 11 | |||
| 12 | =head1 SYNOPSIS | ||
| 13 | |||
| 14 | xlate [ options ] -t LANG FILE [ greple options ] | ||
| 15 | |||
| 16 | Translation options: | ||
| 17 | -h, --help help | ||
| 18 | --version show version | ||
| 19 | -d, --debug debug mode (currently enables trace) | ||
| 20 | --trace trace mode | ||
| 21 | -n, --dryrun dry-run (-nn: preview transmission) | ||
| 22 | -a, --api use API (default; negate with --no-api) | ||
| 23 | -c, --check just check translation area | ||
| 24 | -r, --refresh refresh cache | ||
| 25 | -u, --update force update cache | ||
| 26 | -s, --silent silent mode | ||
| 27 | -t, --to-lang=# target language (required, no default) | ||
| 28 | -b, --from-lang=# base language (informational) | ||
| 29 | -e, --engine=# translation engine (*gpt5, gpt6, deepl, ...) | ||
| 30 | -p, --pattern=# pattern string to determine translation area | ||
| 31 | -f, --file=# pattern file to determine translation area | ||
| 32 | -o, --format=# output format (*xtxt, cm, ifdef, space, space+, colon) | ||
| 33 | -x, --maskfile=# file containing mask patterns | ||
| 34 | -g, --glossary=# glossary file | ||
| 35 | --anonymize=# anonymization dictionary file | ||
| 36 | --mark[=#] collect inline anonymization marks | ||
| 37 | --template[=#] protect template expressions | ||
| 38 | --frontmatter exclude/anonymize YAML front matter | ||
| 39 | --seed=# seed cache from another cache file | ||
| 40 | --context=# context blocks for re-translation | ||
| 41 | --review show minimal source/translation revision spans | ||
| 42 | -w, --wrap=# wrap line by # width | ||
| 43 | -m, --maxlen=# max length per API call | ||
| 44 | -l, --library=# show library files (XLATE.mk, xlate.el) | ||
| 45 | -- end of option | ||
| 46 | N.B. default is marked as * | ||
| 47 | |||
| 48 | Make options: | ||
| 49 | -M, --make run make | ||
| 50 | -n, --dryrun dry-run (make -n) | ||
| 51 | |||
| 52 | Docker options: | ||
| 53 | -D, --docker * run xlate on the container with the same parameters | ||
| 54 | -C, --command * execute following command on the container, or run shell | ||
| 55 | -L, --live * use the live container | ||
| 56 | N.B. These options terminate option handling | ||
| 57 | |||
| 58 | -W, --mount-cwd mount current working directory | ||
| 59 | -H, --mount-home mount home directory | ||
| 60 | -V, --volume=# specify mount directory | ||
| 61 | -U, --unmount do not mount | ||
| 62 | -R, --mount-ro mount read-only | ||
| 63 | -B, --batch run container in batch mode | ||
| 64 | -N, --name=# specify the name of live container | ||
| 65 | -K, --kill kill and remove live container | ||
| 66 | -E, --env=# specify an environment variable to be inherited | ||
| 67 | -I, --image=# docker image or version (default: tecolicom/xlate:version) | ||
| 68 | -P, --port=# port mapping | ||
| 69 | -O, --other=# additional docker option | ||
| 70 | |||
| 71 | Control Files: | ||
| 72 | *.LANG translation languages | ||
| 73 | *.FORMAT translation format (xtxt, cm, ifdef, colon, space) | ||
| 74 | *.ENGINE translation engine (gpt5, gpt6, deepl, ...) | ||
| 75 | *.ANONYMIZE anonymization dictionary for the file | ||
| 76 | |||
| 77 | =head1 VERSION | ||
| 78 | |||
| 79 | Version 2.03 | ||
| 80 | |||
| 81 | =head1 INCOMPATIBLE CHANGES IN 2.0 | ||
| 82 | |||
| 83 | =over 2 | ||
| 84 | |||
| 85 | =item * | ||
| 86 | |||
| 87 | The default translation engine changed from C<deepl> to C<gpt5>. | ||
| 88 | Cache file names include the engine name | ||
| 89 | (F<FILE.xlate-gpt5-LANG.json>), so running without C<-e deepl> | ||
| 90 | creates a new cache for existing DeepL-translated documents. | ||
| 91 | |||
| 92 | =item * | ||
| 93 | |||
| 94 | API translation is now the default. The clipboard-based manual | ||
| 95 | translation mode requires B<--no-api> (the former default); | ||
| 96 | B<-a>/B<--api> remains valid as an explicit default. | ||
| 97 | |||
| 98 | =back | ||
| 99 | |||
| 100 | =cut | ||
| 101 | =head1 DESCRIPTION | ||
| 102 | |||
| 103 | B<XLATE> is a versatile command-line tool designed as a user-friendly | ||
| 104 | frontend for the B<greple> C<-Mxlate> module, simplifying the process | ||
| 105 | of multilingual automatic translation using various API services. It | ||
| 106 | streamlines the interaction with the underlying module, making it | ||
| 107 | easier for users to handle diverse translation needs across multiple | ||
| 108 | file formats and languages. | ||
| 109 | |||
| 110 | A key feature of B<xlate> is its seamless integration with Docker | ||
| 111 | environments, allowing users to quickly set up and use the tool | ||
| 112 | without complex environment configurations. This Docker support | ||
| 113 | ensures consistency across different systems and simplifies | ||
| 114 | deployment, benefiting both individual users and teams working on | ||
| 115 | translation projects. | ||
| 116 | |||
| 117 | B<xlate> supports various document formats, including C<.docx>, | ||
| 118 | C<.pptx>, and C<.md> files, and offers multiple output formats to suit | ||
| 119 | different requirements. By combining Docker capabilities with | ||
| 120 | built-in make functionality, B<xlate> enables powerful automation of | ||
| 121 | translation workflows. This combination facilitates efficient batch | ||
| 122 | processing of multiple files, streamlined project management, and easy | ||
| 123 | integration into continuous integration/continuous deployment (CI/CD) | ||
| 124 | pipelines, significantly enhancing productivity in large-scale | ||
| 125 | localization efforts. | ||
| 126 | |||
| 127 | =head2 Basic Usage | ||
| 128 | |||
| 129 | To translate a file, use the following command: | ||
| 130 | |||
| 131 | xlate -t <target_language> <file> | ||
| 132 | |||
| 133 | For example, to translate a file from English to Japanese: | ||
| 134 | |||
| 135 | xlate -t JA example.txt | ||
| 136 | |||
| 137 | =head2 Translation Engines | ||
| 138 | |||
| 139 | xlate supports multiple translation engines. Use the -e option to | ||
| 140 | specify the engine: | ||
| 141 | |||
| 142 | xlate -e deepl -t JA example.txt | ||
| 143 | |||
| 144 | Available engines: gpt5, gpt6, deepl, ... | ||
| 145 | |||
| 146 | =head2 Output Formats | ||
| 147 | |||
| 148 | Various output formats are supported. Use the -o option to specify the format: | ||
| 149 | |||
| 150 | xlate -o cm -t JA example.txt | ||
| 151 | |||
| 152 | Available formats: xtxt, cm, ifdef, space, space+, colon | ||
| 153 | |||
| 154 | =head2 Docker Support | ||
| 155 | |||
| 156 | B<xlate> offers seamless integration with Docker through the B<dozo> | ||
| 157 | command. Use C<-D> to run xlate in a container, or C<-C> to run | ||
| 158 | arbitrary commands. | ||
| 159 | |||
| 160 | xlate -D -t JA file.txt # run xlate in container | ||
| 161 | xlate -C make # run make in container | ||
| 162 | xlate -DM -t 'EN FR' *.docx # combine with make | ||
| 163 | |||
| 164 | Docker options (C<-I>, C<-E>, C<-W>, C<-H>, C<-V>, C<-U>, C<-R>, | ||
| 165 | C<-B>, C<-N>, C<-K>, C<-L>, C<-P>, C<-O>) are passed to B<dozo>. For details | ||
| 166 | on live containers, container naming, and configuration, see L<App::dozo>. | ||
| 167 | |||
| 168 | B<Note:> The generic Docker runner functionality (C<-C>, C<-L> options) | ||
| 169 | has been moved to the standalone L<App::dozo> command. For running arbitrary | ||
| 170 | commands or managing live containers, use B<dozo> directly. These options | ||
| 171 | in xlate are maintained for backward compatibility but may be deprecated | ||
| 172 | in future versions. | ||
| 173 | |||
| 174 | =head2 Make Support | ||
| 175 | |||
| 176 | xlate utilizes GNU Make for automating and managing translation tasks. | ||
| 177 | This feature is particularly useful for handling translations of | ||
| 178 | multiple files or translations to different languages. | ||
| 179 | |||
| 180 | To use the make feature: | ||
| 181 | |||
| 182 | xlate -M [options] [target] | ||
| 183 | |||
| 184 | xlate provides a specialized Makefile (F<XLATE.mk>) that defines | ||
| 185 | translation tasks and rules. This file is located in the xlate | ||
| 186 | library directory and is automatically used when the -M option is | ||
| 187 | specified. | ||
| 188 | |||
| 189 | Example usage: | ||
| 190 | |||
| 191 | xlate -M -t 'EN FR DE' document.docx | ||
| 192 | |||
| 193 | This command will use make to translate document.docx to English, | ||
| 194 | French, and German, following the rules defined in XLATE.mk. | ||
| 195 | |||
| 196 | The C<-n> option can be used with C<-M> for a dry-run, showing what | ||
| 197 | actions would be taken without actually performing the translations: | ||
| 198 | |||
| 199 | xlate -M -n -t 'EN FR DE' document.docx | ||
| 200 | |||
| 201 | Users can customize the translation process using parameter files: | ||
| 202 | |||
| 203 | =over 4 | ||
| 204 | |||
| 205 | =item F<*.LANG>: | ||
| 206 | |||
| 207 | Specifies target languages for a specific file | ||
| 208 | |||
| 209 | =item F<*.FORMAT>: | ||
| 210 | |||
| 211 | Defines output formats for a specific file | ||
| 212 | |||
| 213 | =item F<*.ENGINE>: | ||
| 214 | |||
| 215 | Selects the translation engine for a specific file | ||
| 216 | |||
| 217 | =back | ||
| 218 | |||
| 219 | For more detailed information on the make functionality and available | ||
| 220 | rules, refer to the F<XLATE.mk> file in the xlate library directory. | ||
| 221 | |||
| 222 | =head1 OPTIONS | ||
| 223 | |||
| 224 | =over 7 | ||
| 225 | |||
| 226 | =item B<-h>, B<--help> | ||
| 227 | |||
| 228 | Show help message. | ||
| 229 | |||
| 230 | =item B<--version> | ||
| 231 | |||
| 232 | Show version information. | ||
| 233 | |||
| 234 | =item B<-d>, B<--debug> | ||
| 235 | |||
| 236 | Enable debug mode. Currently this enables trace mode. | ||
| 237 | |||
| 238 | =item B<--trace> | ||
| 239 | |||
| 240 | Enable trace mode (set -x). | ||
| 241 | |||
| 242 | =item B<-n>, B<--dryrun> | ||
| 243 | |||
| 244 | Given once, print the composed B<greple> command line without | ||
| 245 | executing it. Given twice (C<-nn>), execute the command with | ||
| 246 | C<--xlate-dryrun>: no translation API is called, and each payload is | ||
| 247 | shown exactly as it would be transmitted, after anonymization and | ||
| 248 | masking. In make mode (C<-M>), this option always means C<make -n>. | ||
| 249 | |||
| 250 | =item B<-a>, B<--api> | ||
| 251 | |||
| 252 | Use the translation API. This is the default since 2.0; use | ||
| 253 | B<--no-api> to fall back to the clipboard-based manual translation | ||
| 254 | (labor) mode. In make mode (C<-M>), the clipboard mode is not | ||
| 255 | available; C<XLATE_USEAPI> is kept only for backward compatibility, | ||
| 256 | since the API is used by default regardless of its value. | ||
| 257 | |||
| 258 | =item B<-c>, B<--check> | ||
| 259 | |||
| 260 | Check translation area without performing translation. | ||
| 261 | |||
| 262 | =item B<-r>, B<--refresh> | ||
| 263 | |||
| 264 | Refresh the translation cache. | ||
| 265 | |||
| 266 | =item B<-u>, B<--update> | ||
| 267 | |||
| 268 | Force update of the translation cache. | ||
| 269 | |||
| 270 | =item B<-s>, B<--silent> | ||
| 271 | |||
| 272 | Run in silent mode. | ||
| 273 | |||
| 274 | =item B<-t> I<lang>, B<--to-lang>=I<lang> | ||
| 275 | |||
| 276 | Specify the target language (required). | ||
| 277 | |||
| 278 | =item B<-b> I<lang>, B<--from-lang>=I<lang> | ||
| 279 | |||
| 280 | Specify the base language (optional). | ||
| 281 | |||
| 282 | =item B<-e> I<engine>, B<--engine>=I<engine> | ||
| 283 | |||
| 284 | Specify the translation engine to use. Default is C<gpt5>. | ||
| 285 | |||
| 286 | =item B<-p> I<pattern>, B<--pattern>=I<pattern> | ||
| 287 | |||
| 288 | Specify a pattern to determine the translation area. | ||
| 289 | See L<App::Greple::xlate/NORMALIZATION>. | ||
| 290 | |||
| 291 | =item B<-f> I<file>, B<--file>=I<file> | ||
| 292 | |||
| 293 | Specify a file containing patterns to determine the translation area. | ||
| 294 | See L<App::Greple::xlate/NORMALIZATION>. | ||
| 295 | |||
| 296 | =item B<-o> I<format>, B<--format>=I<format> | ||
| 297 | |||
| 298 | Specify the output format. | ||
| 299 | |||
| 300 | =item B<-x> I<file>, B<--maskfile>=I<file> | ||
| 301 | |||
| 302 | Specify a file containing mask patterns. | ||
| 303 | See L<App::Greple::xlate/MASKING>. | ||
| 304 | |||
| 305 | =item B<-g> I<file>, B<--glossary>=I<file> | ||
| 306 | |||
| 307 | Specify a glossary file. | ||
| 308 | |||
| 309 | =item B<--anonymize>=I<file> | ||
| 310 | |||
| 311 | Anonymize sensitive strings before they are sent to the translation | ||
| 312 | API using the dictionary I<file> (JSON or line format), and restore | ||
| 313 | them in the output. See L<App::Greple::xlate/ANONYMIZATION AND | ||
| 314 | TEMPLATES> for the dictionary format. | ||
| 315 | |||
| 316 | =item B<--mark>[=I<regex>] | ||
| 317 | |||
| 318 | Collect anonymization entries from inline marks in the document, | ||
| 319 | such as C<{{ person("NAME") }}>. An optional I<regex> selects an | ||
| 320 | alternative mark notation; it must contain C<< (?<category>...) >> | ||
| 321 | and C<< (?<text>...) >> named captures. | ||
| 322 | |||
| 323 | =item B<--template>[=I<regex>] | ||
| 324 | |||
| 325 | Treat template expressions (default: Jinja2) as opaque placeholders: | ||
| 326 | they are protected from translation and verified afterwards. | ||
| 327 | |||
| 328 | =item B<--frontmatter> | ||
| 329 | |||
| 330 | Exclude a leading YAML front matter block from translation and add | ||
| 331 | its values to the anonymization rules. Leave a blank line after the | ||
| 332 | closing C<--->. | ||
| 333 | |||
| 334 | =item B<--seed>=I<file> | ||
| 335 | |||
| 336 | Initialize a new document's translation cache from another | ||
| 337 | document's cache I<file>. Useful for periodic reports. | ||
| 338 | |||
| 339 | =item B<--context>=I<n> | ||
| 340 | |||
| 341 | Number of surrounding translated blocks passed as context when | ||
| 342 | re-translating changed blocks (default 2, 0 to disable). | ||
| 343 | |||
| 344 | =item B<--review> | ||
| 345 | |||
| 346 | For a one-to-one block revision, show the minimal changed spans in the | ||
| 347 | source and translation on STDERR. This does not make another API call. | ||
| 348 | |||
| 349 | =item B<-w> I<width>, B<--wrap>=I<width> | ||
| 350 | |||
| 351 | Wrap lines at the specified width. | ||
| 352 | |||
| 353 | =item B<-m> I<length>, B<--maxlen>=I<length> | ||
| 354 | |||
| 355 | Specify the maximum length per API call. | ||
| 356 | |||
| 357 | =item B<-l> I<file>, B<--library>=I<file> | ||
| 358 | |||
| 359 | Show library files (XLATE.mk, xlate.el). | ||
| 360 | |||
| 361 | =back | ||
| 362 | |||
| 363 | =head2 MAKE OPTIONS | ||
| 364 | |||
| 365 | =over 7 | ||
| 366 | |||
| 367 | =item B<-M>, B<--make> | ||
| 368 | |||
| 369 | Run make. | ||
| 370 | |||
| 371 | =item B<-n>, B<--dryrun> | ||
| 372 | |||
| 373 | Dry-run (C<make -n>). | ||
| 374 | |||
| 375 | =back | ||
| 376 | |||
| 377 | =head2 DOCKER OPTIONS | ||
| 378 | |||
| 379 | =over 7 | ||
| 380 | |||
| 381 | =item B<-D>, B<--docker> | ||
| 382 | |||
| 383 | Run B<xlate> on the Docker container with the rest of the parameters. | ||
| 384 | Once this option appears, subsequent options are not interpreted by | ||
| 385 | xlate, so it should always be the last of the xlate options. | ||
| 386 | |||
| 387 | =back | ||
| 388 | |||
| 389 | The following options are specific to L<App::dozo> and are passed through | ||
| 390 | when invoking Docker features. These options are maintained for backward | ||
| 391 | compatibility but may be removed in future versions. For direct container | ||
| 392 | management, use the L<App::dozo> command instead. | ||
| 393 | |||
| 394 | =over 7 | ||
| 395 | |||
| 396 | =item B<-C> [ I<command> ], B<--command> | ||
| 397 | |||
| 398 | Execute command on the Docker container, or run shell if no command. | ||
| 399 | |||
| 400 | =item B<-L> [ I<command> ], B<--live> | ||
| 401 | |||
| 402 | Use live (persistent) container. See L<App::dozo> for details. | ||
| 403 | |||
| 404 | =item B<-W>, B<--mount-cwd> | ||
| 405 | |||
| 406 | Mount current working directory. | ||
| 407 | |||
| 408 | =item B<-H>, B<--mount-home> | ||
| 409 | |||
| 410 | Mount home directory. | ||
| 411 | |||
| 412 | =item B<-U>, B<--unmount> | ||
| 413 | |||
| 414 | Do not mount any directory. | ||
| 415 | |||
| 416 | =item B<-R>, B<--mount-ro> | ||
| 417 | |||
| 418 | Mount read-only. | ||
| 419 | |||
| 420 | =item B<-V> I<from>:I<to>, B<--volume>=I<from>:I<to> | ||
| 421 | |||
| 422 | Additional volume mount. Repeatable. | ||
| 423 | |||
| 424 | =item B<-E> I<name>[=I<value>], B<--env>=I<name>[=I<value>] | ||
| 425 | |||
| 426 | Environment variable to inherit. Repeatable. | ||
| 427 | |||
| 428 | =item B<-I> I<image>, B<--image>=I<image> | ||
| 429 | |||
| 430 | Docker image. Prefix with colon (C<:version>) for default image version. | ||
| 431 | |||
| 432 | =item B<-B>, B<--batch> | ||
| 433 | |||
| 434 | Batch mode (non-interactive). | ||
| 435 | |||
| 436 | =item B<-N> I<name>, B<--name>=I<name> | ||
| 437 | |||
| 438 | Container name for live container. | ||
| 439 | |||
| 440 | =item B<-K>, B<--kill> | ||
| 441 | |||
| 442 | Kill and remove the live container. | ||
| 443 | |||
| 444 | =item B<-P> I<port>, B<--port>=I<port> | ||
| 445 | |||
| 446 | Port mapping (e.g., C<8080:80>). Repeatable. | ||
| 447 | |||
| 448 | =item B<-O> I<option>, B<--other>=I<option> | ||
| 449 | |||
| 450 | Additional docker option. Repeatable. | ||
| 451 | |||
| 452 | =back | ||
| 453 | |||
| 454 | =head1 ENVIRONMENT | ||
| 455 | |||
| 456 | =over 4 | ||
| 457 | |||
| 458 | =item DEEPL_AUTH_KEY | ||
| 459 | |||
| 460 | DeepL API key. | ||
| 461 | |||
| 462 | =item OPENAI_API_KEY | ||
| 463 | |||
| 464 | OpenAI API key. | ||
| 465 | |||
| 466 | =item ANTHROPIC_API_KEY | ||
| 467 | |||
| 468 | Anthropic API key. | ||
| 469 | |||
| 470 | =item LLM_PERPLEXITY_KEY | ||
| 471 | |||
| 472 | Perplexity API key. | ||
| 473 | |||
| 474 | =back | ||
| 475 | |||
| 476 | =head1 FILES | ||
| 477 | |||
| 478 | =over 4 | ||
| 479 | |||
| 480 | =item F<*.LANG> | ||
| 481 | |||
| 482 | Specifies translation languages. | ||
| 483 | |||
| 484 | =item F<*.FORMAT> | ||
| 485 | |||
| 486 | Specifies translation format. | ||
| 487 | |||
| 488 | =item F<*.ENGINE> | ||
| 489 | |||
| 490 | Specifies translation engine. | ||
| 491 | |||
| 492 | =item F<*.ANONYMIZE> | ||
| 493 | |||
| 494 | Anonymization dictionary applied to the file (used by the make | ||
| 495 | workflow; takes precedence over C<XLATE_ANONYMIZE>). | ||
| 496 | |||
| 497 | =back | ||
| 498 | |||
| 499 | =head1 EXAMPLES | ||
| 500 | |||
| 501 | 1. Translate a Word document to English: | ||
| 502 | |||
| 503 | xlate -DMa -t EN-US example.docx | ||
| 504 | |||
| 505 | 2. Translate to multiple languages and formats: | ||
| 506 | |||
| 507 | xlate -M -o 'xtxt ifdef' -t 'EN-US KO ZH' example.docx | ||
| 508 | |||
| 509 | 3. Run a command in Docker container: | ||
| 510 | |||
| 511 | xlate -C sdif -V --nocdif example.EN-US.cm | ||
| 512 | |||
| 513 | 4. Translate without using API (via clipboard-based manual labor): | ||
| 514 | |||
| 515 | xlate --no-api -t JA README.md | ||
| 516 | |||
| 517 | 5. Translate a report template whose actors are defined in YAML front | ||
| 518 | matter, keeping template expressions intact and sending no real | ||
| 519 | names to the API, then render each case with B<pandoc-embedz>: | ||
| 520 | |||
| 521 | xlate -t EN-US --frontmatter --template report-template.md \ | ||
| 522 | > report-template.EN.md | ||
| 523 | pandoc-embedz --standalone report-template.EN.md \ | ||
| 524 | -c case-123.yaml -o report-123.EN.md < /dev/null | ||
| 525 | |||
| 526 | =head1 SEE ALSO | ||
| 527 | |||
| 528 | L<App::Greple::xlate> | ||
| 529 | |||
| 530 | L<App::dozo> - Generic Docker runner used by xlate for container operations | ||
| 531 | |||
| 532 | =head1 AUTHOR | ||
| 533 | |||
| 534 | Kazumasa Utashiro | ||
| 535 | |||
| 536 | =head1 LICENSE | ||
| 537 | |||
| 538 | Copyright © 2023-2026 Kazumasa Utashiro. | ||
| 539 | |||
| 540 | This library is free software; you can redistribute it and/or modify | ||
| 541 | it under the same terms as Perl itself. | ||
| 542 | |||
| 543 | =cut |