blib/lib/App/xlate.pm untested

filter: Statementstmt 0.0% 0 / 1 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 0.0% 0 / 1 SCAR -
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