# jenkins-translation-tool ![Unit tests](https://github.com/glasswalk3r/jenkins-translation-tool/actions/workflows/unit.yaml/badge.svg?branch=main) CLI to generate missing translation keys and missing properties files and remove unused keys for a given language. This is a fork from the original Perl script `translation-tool.pl` available at the [official Jenkins project](https://github.com/jenkinsci/jenkins). ## Differences from the original tool `jtt` is: - faster - uses less memory - better adapted to development best practices When compared to `translation-tool.pl`. ### New features #### Search for terms on translated values For use cases that you need to find a term that is used among the translated files, you can use the `--search` options to do that. If the term is found, warnings are emitted, per file, every time the term was matched. #### Improved online documentation ``` $ jtt --help Usage: jtt --lang=xx options: --dir=directory -> source folder for searching files, optional --help -> print this help message and exits --man -> provides this CLI manpage and exits --lang=xx -> language code to use --add -> optional, generate new files and add new keys to existing files if present --remove -> optional, remove unused key/value pair for existing files if present --counter -> optional, to each translated key, unique value is added to easily identify match missing translation with value in source code if present --target=directory -> optional, target directory for writing files --debug -> optional, print debugging messages to STDOUT when they are available ``` #### Better formatted output Warnings per translation file: ``` Got warnings for core/src/main/resources/hudson/model/Messages_pt_BR.properties: Empty 'HealthReport.EmptyString' Empty 'MultiStageTimeSeries.EMPTY_STRING' Same 'UpdateCenter.PluginCategory.maven' Same 'UpdateCenter.PluginCategory.devops' Same 'UpdateCenter.PluginCategory.devsecops' Same 'JDK.DisplayName' Same 'Hudson.DisplayName' Same 'Item.Permissions.Title' Same 'Queue.Unknown' Same 'Run.Summary.Unknown' ``` This is a translation summary: ``` Translation Status Status Total % ----------------------------- Done 2044 98.64 Missing 0 0 Orphan 5 0.241 Empty 2 0.096 Same 21 1.013 No Jenkins 0 0 ``` ### No caching The script `translation-tool.pl` tried to implement some sort of processing results caching, but that didn't work very well. On the other hand, the script should produce results reasonably fast (~2,7s in a Intel i5-7200U 2.50GHz with encrypted disk), so it's not an issue per see not having it. Cache may be implemented in the future again. ### No encoding conversion The script `translation-tool.pl` tried to convert Jenkins properties from ASCII to UTF-8 and vice-versa using regular expressions. No need to tell how well that worked. The best way to achieve proper encoding that is to use your preferred IDE, see [the suggested workflow](Workflow.md) for more details on that. ### No editor execution `jtt` won't execute a given editor per missing file. This might be seem as a useful feature, but it can become a real issue if you have hundred of files to be open in a IDE. Different IDE's have different ways to handle that (like opening tabs), which might be useful per see, but stills can hog down your computer if too many are required. ### Reviewed command line options Command line options are now properly handled with parsing and validation. ### Always includes original sentences When there are new keys to translate, the original English text will always be included with the `---TranslateMe` prefix (which must be removed, obviously). ### Known terms are skipped Some known key values like URLs and proper names are just ignored when comparing the original values (in English) with the selected language (`--lang`). ### State of Jenkins translations `jtt` also can report the state of translations for all identified language codes in the Jenkins repository: ``` $ jtt --all Hang on, this might take a while. Searching for all translatable files... Warning: ignoring the files at src/test and target/. Done! ✓ Now searching for all available languages... Done! ✓ Now verifying each language translated status... Translation Status Language code % ------------------------ pt_BR 98.98 it 83.67 zh_TW 70.87 bg 66.68 de 66.63 ja 57.82 sr 57.05 es 52.33 ru 44.15 da 42.60 fr 42.32 pl 34.66 lt 30.90 nl 24.98 tr 18.63 lv 14.49 sv_SE 14.10 ko 12.51 sk 11.02 fi 9.484 nb_NO 8.762 cs 8.570 uk 8.088 pt_PT 7.896 he 6.451 et 5.055 ca 4.622 ro 4.188 sl 3.996 el 3.851 es_AR 2.888 zh_CN 0.722 en_GB 0.192 ``` This report was retrieve at 2022-11-15 14:15:18-03:00. ## See also - A suggested [workflow](Workflow.md) to carry on translations with `jtt`. - A bit of [history](History.md) that influenced how design decisions were made to this project. ## Install ### TLDR You will need to have Perl version 5.14 or higher available in your system, which should be default for UNIX-like operational systems like Linux and MacOSX. ``` cpan Jenkins::i18n ``` ### Detailed description There are several ways to install Perl modules, all very well documented by the community. Those external dependencies are all Perl modules available at [CPAN](https://metacpan.org/). Here is a list of ways to do it: 1. Install with [cpan](https://metacpan.org/dist/CPAN/view/scripts/cpan#SYNOPSIS) CLI and [local::lib](https://metacpan.org/pod/local::lib). 2. Install [perlbrew](https://perlbrew.pl/), install your personal `perl` then use `cpan` CLI. 3. Install modules as root using `cpan` CLI: worst and not recommended method. ## Development details ### Dependencies See the `Makefile.PL` file for `TEST_REQUIRES` and `PREREQ_PM` entries: in order to develop, you will need to install by using `cpan` or `cpanm` CLIs. ### Testing Once the dependencies are installed, you can run the tests available for this module: ``` prove -lvm ``` Here is a sample: ``` $ prove -lvm t/Jenkins-i18n.t .... 1..1 ok 1 - use Jenkins::i18n; ok t/removed_unused.t .. 1..15 ok 1 - dies without file parameter ok 2 - get the expected error message ok 3 - dies without keys parameter ok 4 - get the expected error message ok 5 - dies with invalid keys parameter ok 6 - get the expected error message # Without a license ok 7 - got the expected number of keys removed ok 8 - resulting properties file has the expected number of lines ok 9 - dies with invalid license parameter ok 10 - get the expected error message # Restoring file # With a license ok 11 - got the expected number of keys removed ok 12 - resulting properties file has the expected number of lines # Restoring file # With a backup ok 13 - got the expected number of keys removed ok 14 - resulting properties file has the expected number of lines ok 15 - File has a backup as expected ok All tests successful. Files=2, Tests=16, 0 wallclock secs ( 0.02 usr 0.00 sys + 0.14 cusr 0.01 csys = 0.17 CPU) Result: PASS ``` You can also get testing coverage if `Devel::Cover` is installed: ``` ~/jenkins-translation-tool$ perl Makefile.PL Generating a Unix-style Makefile Writing Makefile for Jenkins::i18n Writing MYMETA.yml and MYMETA.json ~/jenkins-translation-tool$ make Skip blib/lib/Jenkins/bench.pl (unchanged) Skip blib/lib/Jenkins/i18n/Warnings.pm (unchanged) Skip blib/lib/Jenkins/i18n/Stats.pm (unchanged) Skip blib/lib/Jenkins/i18n/ProcOpts.pm (unchanged) Skip blib/lib/Jenkins/i18n.pm (unchanged) cp lib/Jenkins/i18n/Properties.pm blib/lib/Jenkins/i18n/Properties.pm cp bin/jtt blib/script/jtt "perl" -MExtUtils::MY -e 'MY->fixin(shift)' -- blib/script/jtt Manifying 1 pod document Manifying 5 pod documents jenkins-translation-tool$ cover -test Deleting database ~/jenkins-translation-tool/cover_db cover: running make test "OPTIMIZE=-O0 -fprofile-arcs -ftest-coverage" "OTHERLDFLAGS=-fprofile-arcs -ftest-coverage" PERL_DL_NONLAZY=1 "perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t t/find_files.t ....... ok t/Jenkins-i18n.t ..... ok t/load_jelly.t ....... ok t/load_properties.t .. ok t/proc_opts.t ........ ok t/removed_unused.t ... ok t/stats.t ............ ok t/warnings.t ......... ok All tests successful. Files=8, Tests=99, 3 wallclock secs ( 0.04 usr 0.00 sys + 2.53 cusr 0.17 csys = 2.74 CPU) Result: PASS Reading database from ~/jenkins-translation-tool/cover_db ---------------------------- ------ ------ ------ ------ ------ ------ ------ File stmt bran cond sub pod time total ---------------------------- ------ ------ ------ ------ ------ ------ ------ blib/lib/Jenkins/i18n.pm 91.2 78.5 66.6 92.8 100.0 72.3 87.3 .../Jenkins/i18n/ProcOpts.pm 100.0 100.0 66.6 100.0 100.0 7.5 98.9 ...enkins/i18n/Properties.pm 100.0 66.6 33.3 100.0 100.0 6.2 88.3 ...lib/Jenkins/i18n/Stats.pm 78.9 83.3 n/a 100.0 100.0 6.8 83.6 .../Jenkins/i18n/Warnings.pm 97.3 90.0 n/a 100.0 100.0 6.9 96.4 Total 94.2 80.4 53.3 98.3 100.0 100.0 91.3 ---------------------------- ------ ------ ------ ------ ------ ------ ------ HTML output written to ~/jenkins-translation-tool/cover_db/coverage.html done. ``` ## References - [Jenkins Internationalization](https://www.jenkins.io/doc/developer/internationalization/) - [i18n](https://wiki.mageia.org/en/What_is_i18n,_what_is_l10n) - [Online convertion of UTF-8 to Java entities](http://itpro.cz/juniconv/) - Introduction to Jelly: https://youtu.be/_MhWugMQegs?list=PLCOmiTb5WX3ouggdJ4ty2dVUSrki9uYr1&t=373 ## Copyright and licence This software is copyright (c) 2022 of Alceu Rodrigues de Freitas Junior, arfreitas at cpan.org This file is part of Jenkins Translation Tool project. Jenkins Translation Tool is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Jenkins Translation Tool is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Jenkins Translation Tool. If not, see (http://www.gnu.org/licenses/). The original `translation-tool.pl` script was licensed through the MIT License, copyright (c) 2004-, Kohsuke Kawaguchi, Sun Microsystems, Inc., and a number of other of contributors. Translations files generated by the Jenkins Translation Tool CLI are distributed with the same MIT License.