{"id":19777525,"url":"https://github.com/ilib-js/loctool","last_synced_at":"2025-04-30T19:32:40.551Z","repository":{"id":26860642,"uuid":"110168224","full_name":"iLib-js/loctool","owner":"iLib-js","description":"A localization tool that scans source code looking for localizable strings and writes out translated resource files","archived":false,"fork":false,"pushed_at":"2024-04-15T01:58:18.000Z","size":182074,"stargazers_count":11,"open_issues_count":4,"forks_count":4,"subscribers_count":9,"default_branch":"development","last_synced_at":"2024-04-23T02:38:58.841Z","etag":null,"topics":["localization"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iLib-js.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-09T21:29:16.000Z","updated_at":"2024-05-21T18:29:20.456Z","dependencies_parsed_at":"2023-11-26T13:16:32.919Z","dependency_job_id":"69abaa3e-0d1e-4a5a-a433-0821a743d7a1","html_url":"https://github.com/iLib-js/loctool","commit_stats":{"total_commits":2473,"total_committers":27,"mean_commits":91.5925925925926,"dds":0.6045289122523252,"last_synced_commit":"3508e2d836adbfb560907d103f67124fc2f23b86"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Floctool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Floctool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Floctool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Floctool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iLib-js","download_url":"https://codeload.github.com/iLib-js/loctool/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224222375,"owners_count":17275993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["localization"],"created_at":"2024-11-12T05:25:23.888Z","updated_at":"2025-04-30T19:32:40.543Z","avatar_url":"https://github.com/iLib-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003e :warning: **Deprecation Notice** :warning:\n\u003e This repository has been deprecated. Please use the corresponding package from the [iLib-js monorepo](https://github.com/iLib-js/ilib-mono) instead.\n\nLocalization Tool\n=================\n\nThis tool reads source files in various formats, extracts strings\nfor translation, and writes out the translated strings the various\nresource file formats needed by each project.\n\nSee the [release notes](./docs/ReleaseNotes.md) for details on what is\nnew and what has changed.\n\nInstallation\n------------\n\nTo install the loctool, you will need to make sure you have nodejs installed\non your machine and in your path, as this is used to run the code. (Use 7.0 or later)\n\nOnce nodejs is installed, you can install the loctool itself. You can either\nget it from npm or from github.com:\n\n1. By npm is simple: `npm install loctool` or to install it globally: `npm install -g loctool`.\n(Alternately, `yarn add loctool`)\n\n1. By github is a little more complicated in that you still need npm to install\nthe necessary JS libraries that the loctool depends upon:\n\n```\ngit clone git@github.com:iLib-js/loctool.git\ncd loctool\nnpm install\n```\n\nIf you did these steps, you can run it in situ as if it were installed by npm.\nThe difference is that now you can make a branch and recontribute your fixes as\nPRs back to the open-source community. Better would be if you made a fork first\nand submitted PRs from your fork instead.\n\nRunning the Tool\n----------------\n\n### Basic Operation\n\n1. Create a project.json configuration file for your project\n1. Run the loctool to produce a set of xliff files with new strings to translate in them\n1. Send the xliff files to your translators for translation and, some time\nlater, receive the translations back\n1. Make the translations available into your project\n1. Run the loctool again to produce a set of translated files and a set\nof new xliff files. The new xliff files contain all the new or changed strings\nsince the last time that the loctool was run.\n\n### Configuration\n\nTo run the tool, you will need to create a project.json configuration file for\neach project and place it in the root of that project. The presence of a project.json\nfile indicates to the loctool that it has found the root of a project.\n\nThe easiest way to create a new project.json file for a particular directory is\nto use the `loctool init` command. This will ask you a few questions and generate\na new project.json file in the current directory. You can use this as a starting\npoint for your project, and then edit it to customize any settings.\n\n```\n\u003e node node_modules/.bin/loctool.js init\n22:52:56 INFO loctool.loctool: loctool - extract strings from source code.\n\n22:52:56 INFO loctool.loctool: Command: init\nloctool v2.12.0 Copyright (c) 2016-2017, 2019-2021, HealthTap, Inc. and JEDLSoft\nProject Initialize\nFull name of this project: myproject\nType of this project (web, swift, iosobjc, android, custom) [custom]:\nSource locale [en-US]:\n22:52:57 INFO loctool.loctool: Wrote file project.json\n22:52:57 INFO loctool.loctool: Done\n\u003e cat project.json\n{\n    \"name\": \"myproject\",\n    \"id\": \"myproject\",\n    \"sourceLocale\": \"en-US\",\n    \"pseudoLocale\": \"zxx-XX\",\n    \"resourceDirs\": {\n        \"javascript\": \"target\",\n        \"md\": \"target\"\n    },\n    \"includes\": [],\n    \"excludes\": [\n        \".git\",\n        \".github\",\n        \"test\",\n        \"node_modules\"\n    ],\n    \"settings\": {\n        \"locales\": [\n            \"en-GB\",\n            \"de-DE\",\n            \"fr-FR\",\n            \"it-IT\",\n            \"es-ES\",\n            \"pt-BR\",\n            \"ja-JP\",\n            \"zh-Hans-CN\",\n            \"ko-KR\"\n        ]\n    },\n    \"projectType\": \"custom\",\n    \"plugins\": [\n        \"javascript\",\n        \"javascript-resource\",\n        \"ghfm\"\n    ]\n}\n\u003e\n```\n\nThe project.json file minimally contains the name, id, and projectType\nproperties.\n\nAll paths are relative to the root of the project.\n\n* name - the human-readable name of the project\n* id - the unique id of the project, which also determines the\n    name of the xliff file the tool looks for. (ie. if your\n    project is \"X\", then it will look for \"X.xliff\")\n* projectType - the type of the project, which affects how source files\n    are read and resource files are written. Must be one of\n    \"android\", \"iosobjc\", \"iosswift\", or \"web\", or \"custom\".\n    * android - an android project\n    * iosobjc - an iOS project using Objective-C\n    * iosswift - an iOS project using Swift\n    * web - a web application\n    * custom - a project using a custom set of plugins to process\n    all of the files (see below)\n* resourceDirs - an object that maps a file type to a dir that serves\n    as the out for resource files\n* excludes - an array of dirs or files to exclude from searching. When\n    a dir is excluded, all subfiles and subdirs in that dir\n    are also excluded.\n* includes - an array of dirs or files to localize. These override the\n    excludes. This allows you to exclude an entire directory\n    but localize particular files in that directory.\n* settings - other settings which configure this project. Some important\n    settings:\n    * locales - an array of target locales\n    * xliffsDir - directory containing input translation xliff files\n    * xliffsOut - where to place the output xliff files, such as\n    the \"new\" strings files\n* plugins - an array of names of plugins to use that handle various file\n  types in your project. Make sure you have put these plugins as dependencies\n  in your package.json. See the plugins section below for more information\n  about them.\n\nBoth the \"includes\" and \"excludes\" arrays may contain enhanced glob\nwildcard expressions using the [minimatch syntax](https://github.com/isaacs/minimatch):\n\n* `*` - any sequence of characters in the current dir\n* `?` - any particular character\n* `**` - any sequence of directories\n\nExample: `**/*.js` finds all javascript files, in whatever subdirectory.\n\nThis is a similar syntax to that used in ant's build.xml files. See the\nminimatch documentation for more details.\n\n### Making your Translations Available\n\nYou will need to get the xliff files that contain the translations into\nyour project so the loctool can find them. There are two ways to do this:\n\n1. If you are using xliff v1.2 format, you can have all your translations in\na single file. Put this file into the root of your project. This file should\nhave the same base name as your project id in the project.json file. For\nexample, if your project is called \"foo\" in the project.json file, you should have\na foo.xliff file in your root that contains all the translations.\n1. If you have multiple translation files, you can put them in a single\ndirectory, and update the settings in the project.json to point to that\ndirectory. The loctool will read all of the xliff files in that directory.\nThis will allow you do things like keep each batch of translations in a separate\nset of xliff files from the old ones that don't need to be merged.\n\nExample settings for an xliffs directory:\n\n```json\n{\n    \"name\": \"myproject\",\n    \"id\": \"myproject\",\n    ...\n    \"settings\": {\n        \"xliffsDir\": \"translations\"\n    },\n}\n```\n\n### Running the Loctool\n\nRunning the tool is pretty straight-forward. Check out all the source code you\nwould like to localize to a particular directory and make sure that the current\nbranch is the one you would like to localize.\n\nTo run the tool:\n\n```\nnode \u003cpath-to-the-loctool-dir\u003e/loctool.js\n```\n\nor if you have node_modules/.bin in your path already,\nyou can simply run the \"loctool\" script which will launch node for\nyou.\n\nNote that using the defaults for almost all parameters will usually\nget you what you want. See below for a description of the command-line\nparameters.\n\nThe result is that it will find all localizable strings for your\nproject, and write them to an \"new strings\" xliff file for each\ntarget locale. If your project id is \"foo\", then it will produce files:\n\n```\nfoo-new-es-ES.xliff\nfoo-new-de-DE.xliff\nfoo-new-fr-FR.xliff\netc...\n```\n\nOne for each target locale.\n\n### Translating the Strings\n\nYou can hand these new xliff files to\nyour translation vendor. XLIFF is a localization industry standard\nand pretty much any reputable translation house will know\nwhat to do with xliff files.\n\nNote that if your vendor requires xliff v2.0 format\nfiles instead of v1.2, you can generate them using the \"-2\"\ncommand-line parameter.\n\n### Re-integrating the Translated Files\n\nWhen you have the translations back from your translators, you can\neither merge them all together along with the existing\ntranslations into one long xliff file named for the project\n(only available for xliff v1.2 format files). Alternately, you can\nmake sure the files names are unique, and place them into a single\ndirectory and use the xliffsDir setting in your project.json file\nto point the loctool at that dir.\n\nTo merge a set of xliff files into one:\n\n```\nloctool merge \u003coutput-file\u003e \u003cinput-file\u003e ...\n```\n\nThat is, the arguments are the name the output file (eg. \"foo.xml\")\nand the list all the input files. Make sure to include your existing\ntranslations in the list of input files or else you will lose all\nyour old translations! You want to merge all the old and new translations\ntogether into one file.\n\n```\nloctool merge temp.xliff foo.xliff foo-new-de-DE.xliff foo-new-fr-FR.xliff foo-new-ja-JP.xliff\nmv temp.xliff foo.xliff\n```\n\n### Run the Loctool Again\n\nNow when you run the loctool, it will do two things. First,\nit will write out the newly translated strings into resource files (eg. Java\nproperties files) or translated files (eg. translated copies of HTML files)\nthat are appropriate to your app's programming languages. Second, it will\nsearch for any new or changed strings that have been added since you sent out\nyour last batch of translations. It will place those\nin the foo-new-*.xliff files, which you can then send to the translators\nas your next batch.\n\nBecause it does both at the same time, you can use the loctool as the engine\nfor continuous localization. As soon as you receive a batch of translations\nback from the vendor, you immediately make the next batch!\n\n### When to Run the Loctool\n\nThe loctool can be used in one of a number of ways:\n\n1. In the build. The loctool can be run as a step in the build\nbetween the \"get all the source code from your SCM\" step, and\nthe \"compile all the source code\" step. In this case, you will\nprobably want to check in the translated XLIFF files to your\nSCM so that the loctool has the translations available as it\nruns. This has the advantage that you can get a reproducible,\nstable build because the xliffs are also under source control.\n\n1. Manually. The localization manager can run the loctool\non-demand and then check in the results to the SCM. They can do this\non a regular basis to produce the new strings files each time.\nThis method is good when the project is small and there is\nnot a lot of reason to translate frequently and regularly.\n\n1. In a background job. If your project is large and there is a\nconstant stream of new strings to translate, you can use a CI\nsystems like Jenkins or Travis or CircleCI to automate things.\nFirst, check in the translated xliffs from your vendor into a\nseparate SCM repository. Then create a CI task that runs on a regular\nbasis and gets the latest xliffs from the xliffs repo, and the latest\nsource code from your SCM repo, and then runs the loctool on it. The end\nresult is that the task should create a pull request/check-in/review\nfor any of the localized files that the loctool has generated.\nIf it is set up correctly, this job can be triggered automatically\nany time a change is pushed into your xliffs repo. This will\nmake sure that the latest localized files are always checked in to\nyour SCM soon after you receive each batch of translations back\nfrom your vendor.\n\nPseudotranslation\n-----------------\n\nThe loctool has the ability to do pseudo-translation, which means\nautomatically generating a set of translations as a transformation of\nthe source strings. Currently, there are two types of pseudo-translations:\n\n1. Pseudo-translation for debugging. This transformation takes a source\nstring and applies an algorithmic transformation to it for the purpose\nof debugging your app.\n1. Automatic translation. This applies an algorithmic translation to\nthe source strings for actual use in your app.\n1. Transliterations. This applies an algorithm to transform one\n[manual] translation into another in a different script.\n\n### Debug Pseudo-translation\n\nThe reasons you might use debug pseudo-translation are:\n\n1. To test whether all your strings have been extracted properly. If\nyou rely on your engineers to either wrap their translatable strings\nin function calls, or for them to copy their strings into a source\nresource file, they may miss some of them. Using a pseudo locale\nin your UI will make that obvious. If you see a regular source\nstring in your UI instead of a pseudo-localized one, then either:\n    1. The engineer missed it\n    1. It is a user-generated string\n    1. It comes from outside your app (ie. a 3rd party app,\n       library, file, or service.)\nIf is it the first type, then you can submit a bug for the engineer\nto fix it.\n1. To test if long strings will fit in your UI. The source string\nis artificially lengthened to simulate \"long\" languages like\nGerman or French that tend to cause expansion from English source\nstrings. Ideally, your UI is dynamically sized and can stretch\nappropriately to accommodate translations that are longer or\nshorter than the source string.\n1. To test fonts. Some pseudo translations can transform the\nsource strings into strings of characters that require a different\nfont. This allows you to test out whether or not the font works\nin your UI without having a real translation.\n\n### Automatic Translations\n\nStrings for some locales can be generated based on the source\nlocale strings or based on previous translations. Here are\nthe transformations that the loctool currently supports:\n\n1. US English -\u003e British English. This is essentially a spell\ncorrection from US English to British English. For example,\nit will correct (color -\u003e colour) and (localize -\u003e localise).\nIt will not take care of transforming vocabulary such as\n(truck -\u003e lorry) or (sweater -\u003e jumper).\n1. US English -\u003e Canadian English. Similar to the British\nEnglish, this is simply a spell correction without transforming\nvocabulary.\n1. US English -\u003e Australian English. Similar to the British\nEnglish, this is simply a spell correction without transforming\nvocabulary. This transformation is almost the same as\nBritish English except for a few slight differences.\n1. US English -\u003e New Zealand English. Similar to the British\nEnglish, this is simply a spell correction without transforming\nvocabulary. This transformation is almost the same as\nBritish English except for a few slight differences.\n1. US English -\u003e another form of English not listed above.\nThis applies the British English rules to generate the other\nlocales. For example, en-JM (English for Jamaica) can be\ngenerated from US English using the British English spell\ncorrections.\n\nFuture versions of the loctool may contain automatic translations\nbased on machine translation. For example, if your company\nhas a license to use the Google Translate API, we could use\nthat to generate translations automatically. The quality of\nmachine translation is not sufficient to look \"professional\"\nin a regular UIs but could be of use to support locales that\nare not your core business or perhaps even for pre-testing\nlocales before you spend money on real translation.\n\nOne big problem with Google Translate and the reason that the\nGoogle Translate automatic pseudo-translation does not yet exist\nin the loctool is that Google Translate is not designed\nfor UI strings. This causes a number of problems:\n\n1. Markup or HTML gets messed and the syntax is wrong.\nSometimes even, the HTML tag names of attribute names\nget translated!\n1. Substitution parameter names get translated for those\nprogramming languages that name their parameters.\n1. The syntax of substitution parameters can get screwed\nup for those programming languages where the parameters\nare not named. Example: \"%@1s\" -\u003e \"%  @1 s\" in some\ninstances and the programming language no longer recognizes\nthem as substitution parameters.\n1. The position of substitution parameters is not updated.\nHuman translators realize that \"%s\" in a source string\nis substituted with a particular type of value, especially\nif this is explained in your extracted translator's\ncomments. For example, \"%s\" may represent a person's\nname or a formatted date, and \"%d\" may represent a number\nof items. Google Translate will not move these around\nin the translation appropriately according to the grammar\nof the language, but a human translator will.\n\n### Transliterations\n\nCurrently, only one type of transliteration is supported, but\nmore are planned for future versions of the loctool.\n\nThis type of pseudo-translation is\nis a little special in that it is not the source string that is\ntransformed, but a previous translation of that source string.\nIn order to use this\npseudo-translation, you have to localize to both the\nlocales in the same run of the\nlocalization tool. That is, both must be listed in the\n`locales` setting at the same time. If they are not done\ntogether, then the translation to the first locale is not\navailable to be mapped into the translation for the second\nlocale.\n\nSupported transliterations are:\n\n1. Simplified Chinese -\u003e Traditional Chinese. This applies\nthe open-source OpenCC transformation that is used in Wikimedia\nto automatically generate the traditional Chinese based on\na previous simplified Chinese translation. Both the Taiwan and\nHong Kong style of traditional Chinese are supported,\nbased on the target locale.\n\nOther types of automatic translations are planned in\nfuture versions of the loctool:\n\n1. Serbian. Cyrillic \u003c-\u003e Latin\n1. Uzbek. Cyrillic \u003c-\u003e Latin \u003c-\u003e Arabic\n1. Kurdish. Cyrillic \u003c-\u003e Latin \u003c-\u003e Arabic\n1. Japanese Katakana \u003c-\u003e Romaji\n\nIf you have a request for any other type of transliteration,\nplease let us know!\n\n## Specifying Pseudo-translations\n\nPseudo-translations can be specified in your project.json file.\nCurrently, there are two properties of the project.json that\nare involved with pseudo-translation:\n\n1. pseudoLocale: This is either a string, an array of locale specs,\nor an object that maps locale specs to a pseudo-translation style.\n1. settings.locales: If you wish to perform a pseudo-translation,\nthe target locale for that pseudo-translation must be listed in\nthe settings.locales array. If you are doing a transliteration,\nfor example, from simplified Chinese for China (zh-Hans-CN) to\ntraditional Chinese for Taiwan (zh-Hant-TW), both of those locales\nshould be listed in the settings.locales array.\n\nIf pseudoLocales is specified as:\n\n* string: this specifies a single locale to use as the \"debug\"\npseudo-translation\n* array: all of the locales listed in the array will be\nconsidered pseudo-locales and the default pseudo-translation style\nwill be applied to generate them.\nAny locale not specified in the array will not be considered a\npseudo-locale.\n* object: map locale specs to the style of pseudo-translation.\n* empty array or object: all pseudo-translations will be turned off.\n* not specfied at all: all available pseudo-translations listed above will\nbe applied with their default style.\n\nExample project.json with a string pseudo locale:\n\n```\n{\n  \"pseudoLocale\": \"mn-MN\",\n  \"settings\": {\n    \"locales\": [ \"de-DE\", \"en-CA\", \"en-GB\", \"mn-MN\", \"zh-Hans-CN\", \"zh-Hant-TW\"]\n  }\n}\n```\n\nThis uses \"mn-MN\" for the \"debug\" pseudo-translation. Note that \"mn-MN\" must be listed in\nthe `settings.locales` for this to work.\n\nExample project.json with an array of pseudo locales:\n\n```\n{\n  \"pseudoLocale\": [\n    \"en-CA\",\n    \"en-GB\",\n    \"zh-Hant-TW\"\n  ],\n  \"settings\": {\n    \"locales\": [ \"de-DE\", \"en-CA\", \"en-GB\", \"zh-Hans-CN\", \"zh-Hant-TW\"]\n  }\n}\n```\n\nNote that both \"zh-Hans-CN\" and \"zh-Hant-TW\" are listed in the locales so that\nthe Taiwan resources can be generated from the China resources.\n\nExample project with an object of pseudo locales:\n\n```\n{\n  \"pseudoLocale\": {\n    \"pl-PL\": \"debug\",\n    \"am-XX\": \"debug-font,\n    \"en-CA\": \"english-canadian\",\n    \"en-GB\": \"english-british\",\n    \"zh-Hant-TW\": \"chinese-traditional-tw\"\n  },\n  \"settings\": {\n    \"locales\": [ \"de-DE\", \"en-CA\", \"en-GB\", \"pl-PL\", \"zh-Hans-CN\", \"zh-Hant-TW\"]\n  }\n}\n```\n\nIn the above example, we are co-opting the Polish locale\nas the \"debug\" pseudo-translation. Make sure Polish is also\nlisted in the locales list!\n\n### Pseudo-translations Styles and Defaults\n\nThe following is the list of styles supported:\n\n- debug: map Latin characters to accented versions of those\n  characters. This is readable in English still, albeit with some\n  difficulty, so that you can use the UI.\n- debug-rtl: map the Latin characters to right-to-left language\n  characters to test your app's readiness for right-to-left languages\n  like Arabic or Hebrew\n- debug-han-simplified: map the Latin characters to Simplified Chinese characters\n  to test your app's font support for Chinese characters\n- debug-font: map the Latin characters to characters that\n  require a different font.\n- english-british: map US spellings to British English spellings\n- english-canadian: map US spellings to Canadian English spellings\n- english-australian: map US spellings to Australian English spellings\n- english-new-zealand: map US spellings to New Zealand English spellings\n- chinese-traditional-tw: map simplified Chinese translations\n  to Taiwan-style traditional Chinese\n- chinese-traditional-hk: map simplified Chinese translations\n  to Hong Kong-style traditional Chinese\n\nThe following is the default mapping between locales (pseudo-locales!)\nand the styles:\n\n- zxx-XX, und-XX: debug\n- zxx-Arab-XX: debug-rtl\n- zxx-Hans-XX, zxx-Hant-XX: debug-han-simplified\n- en-CA: english-canadian\n- en-AU, en-CX, en-CC, en-NF, en-HM: english-australian\n- en-NZ, en-CK, en-NU, en-TK: english-new-zealand\n- en-*: english-british  (that is, any form of English other than\n  the ones listed above)\n- zh-Hant: chinese-traditional-tw\n- zh-Hant-TW: chinese-traditional-tw\n- zh-Hant-HK: chinese-traditional-hk\n\nNote that \"zxx\" means \"unspecified language\", and \"und\" means\n\"undefined language\", which are valid ISO codes that are never\nused in real locales so they\nmake good candidates for debug pseudo-translations. However, there are\nmany UI frameworks that do not allow you to set the locale\nto these locales. In that case, you might want to choose a locale\nthat you are not currently officially supporting like \"be-BE\" or\n\"fi-FI\" but which are more common and which your UI framework\nwill allow. Be very careful to not ship this locale!\n\nPlugins\n-------\nThe loctool is driven by plugins that know how to parse various types\nof files, and write out the appropriate localized output.\n\nPlugins can be loaded dynamically using the \"custom\" type of project\nand listing out the required plugins in the \"plugins\" section of\nthe project.json config file. Plugins are implemented as separate node\nmodules similar to the way Babel or Webpack plugins are implemented.\n\nIf you encounter a file type that the loctool doesn't currently\nhandle, or which it is handling in a way that you don't like, you can\nwrite your own plugin. A plugin is simply two classes\nthat conform to a simple SPI. If you would like to write one,\nread the [How to Write a Loctool Plugin](docs/Plugins.md)\ndocumentation for all the details.\n\nList of Current Plugins\n-----------------------\n\n* `ilib-loctool-android-layout` - extract strings from\nAndroid layout.xml files and produce translated\nstrings.xml files\n\n* `ilib-loctool-android-resource` - extract strings from\nAndroid strings.xml files and produce translated\nstrings.xml files\n\n* `ilib-loctool-csv` - extract strings from comma-separated\nvalues (CSV) format files and produce translated CSV files\n\n* `ilib-loctool-ghfm` - extract strings from Github-Flavored\nMarkdown (MD) format files and produce translated MD files\n\n* `ilib-loctool-ghfm-readmeio` - extract strings from Github-Flavored\nMarkdown (MD) format files with Readme.io extensions and\nproduce translated MD files\n\n* `ilib-loctool-haml` - extract strings from HAML format\nfiles and produce translated HAML files\n\n* `ilib-loctool-html` - extract strings from static HTML\nfiles and produce translated HTML files\n\n* `ilib-loctool-jst` - extract strings from Javascript Template\n(JST) code files and produce translated JST files\n\n* `ilib-loctool-strings` - extract strings from iOS\n.strings format resource files and produce other .strings files\n\n* `ilib-loctool-java` - extract strings from Java\ncode that uses the ilib ResBundle class to do its translations\nand produce properties resource files\n\n* `ilib-loctool-javascript` - extract strings from Javascript\ncode that uses ilib to do its translations and produce JS\nresource files\n\n* `ilib-loctool-javascript-resource` - extract strings from ilib\nJavascript resource files and produce JS resource files\n\n* `ilib-loctool-jsx` - extract strings from JSX format\ncode that uses ilib and react-ilib to do its translations\n\n* `ilib-loctool-jst` - extract strings from JavaScript Template\n(JST) format files\n\n* `ilib-loctool-objectivec` - extract strings from Objective-C\ncode for iOS and produce .strings files\n\n* `ilib-loctool-swift` - extract strings from Swift\ncode for iOS and produce .strings files\n\n* `ilib-loctool-yaml` - extract strings from YAML format\nfiles and produce translated YAML files\n\n* `ilib-loctool-xliff` - extract strings from XLIFF\nformat files and produce translated XLIFF files\n\n* `ilib-loctool-webos-appinfo-json` - extract strings webOS\n  appinfo.json files and produce translated appinfo.json files for webOS\n\n* `ilib-loctool-webos-c` - extract strings from C language\n  files for webOS\n\n* `ilib-loctool-webos-cpp` - extract strings from C++ language\n  files for webOS\n\n* `ilib-loctool-webos-javascript` - extract strings from Javascript language\n  files for webOS\n\n* `ilib-loctool-webos-json-resource` - extract strings from javascript, C/C++ files\n and produce translated json files for webOS\n\n* `ilib-loctool-webos-qml` - extract strings from QML language\n  files for webOS\n\n* `ilib-loctool-webos-ts-resource` - extract strings from webOS QML files\n and produce translated QT's TS format files for webOS\n\n* `ilib-loctool-salesforce-metaxml` - extract strings from -meta.xml files and produced translated\n  meta.xml files for Salesforce\n\n* `ilib-loctool-json` - extract strings from json files and produce translated json files. This\nspecifies which strings to extract using a json schema file. Different json files can use different\njson schemas.\n\n* `ilib-loctool-po` - extract strings from po files and produce translated po files\n\n* `ilib-loctool-xml` - extract strings from XML files and produce translated XML files. This\nspecifies which strings to extract using a schema file. Different XML files can use different schemas.\n\nConfiguring a Custom Project Type\n-----------------------------------------------\n\nLet's say you have a web project that uses Javascript,\nJST, and HTML on the front end, and you would like to\nlocalize it using loctool.\n\nIn this case, you need to make sure to add `loctool`,\n`ilib-loctool-jst`, `ilib-loctool-html`, and\n`ilib-loctool-javascript` to the dependencies property\nof your package.json file:\n\n```\n  ...\n  \"devDependencies\": {\n    \"loctool\": \"^2.3.0\",\n    \"ilib-loctool-jst\": \"^1.0.0\",\n    \"ilib-loctool-html\", \"^1.0.0\",\n    \"ilib-loctool-javascript\": \"^1.0.0\"\n  },\n  ...\n```\n\nThen, you need to add a \"plugins\" property to the project.json\nfile which is an array of plugin names. The plugins may be\nreferred to with their whole name from npm, like\n\"ilib-loctool-jst\", or it can be referred to by the part\nafter the \"ilib-loctool-\", so just \"jst\" in this example.\n\nHere is what your custom project.json might look like:\n\n\n```\n{\n    \"name\": \"My Web App\",\n    \"id\": \"mywebapp\",\n    \"projectType\": \"custom\",\n    \"sourceLocale\": \"en-US\",\n    \"pseudoLocale\": \"sw\",\n    \"resourceDirs\": {\n        \"jst\": \"./i18n\",\n        \"javascript\": \"./i18n\"\n    },\n    \"plugins\": [\n        \"jst\",\n        \"html\",\n        \"javascript\"\n    ],\n    \"excludes\": [\n        \"./.git\",\n        \"./assets\",\n        \"./bin\",\n        \"./libs\",\n        \"./script/**/*.sh\",\n        \"./classes\"\n    ],\n    \"includes: [\n        \"**/*.html\",\n        \"**/*.jst\",\n        \"**/*.js\"\n    ],\n    settings: {\n        locales: [\"es-ES\", \"de-DE\", \"fr-FR\"],\n    }\n}\n```\n\nLoctool in your Path\n-------------------\n\nIf you have \"node_modules/.bin\" in your path, then you can run\nthe loctool with just a simple `loctool` command. Otherwise,\nyou will have to put \"node_modules/.bin\" in your path, or specify\nthe path to the loctool explicitly on the command-line.\n\nYou can avoid adding the .bin directory to your path if you\nare using scripts in the package.json. The \"node_modules/.bin\"\ndirectory is automatically added to the path, so you can create\na script like this in your package.json without the explicit\npath:\n\n```\n\"scripts\": {\n    \"loc\": \"loctool\"\n},\n```\n\nThen:\n\n```\nnpm run loc\n```\n\nOther Actions the Loctool Can Do\n-------\n\nAll of the above documentation is focussed on localization, which is the\nmain function of the loctool and it is the default action. There are a\nfew other things that the loctool can do as well, and these are specified\non the command line as the 2nd parameter, similar to the way that\nactions are specified to git or npm.\n\nThese are the actions which are available:\n\n- localize - localize any projects found in the current directory tree.\n  This is the default action.\n- init - create a new project.json file based on the answers to a few\n  questions. This makes it easy to set up a new project for localization.\n- merge - merge multiple xliff files together into one. There may be some\n  restrictions to this, as xliff v2.0 format files cannot contain translations\n  to multiple languages.\n- split - split a set of xliff files into multiple xliff files where each\n  output file contains one language or project.\n- generate - like the localize action, this generates a set of localized\n  files for the project. However, unlike the localize action, it does not\n  read the source files first to determine which strings are used nor does\n  it generate a new strings file.\n- convert - Converts one resource file format to another. Resource files\n  are files that contain a collection of translations for a product in a\n  particular programming language. Examples include xliff, po, json,\n  strings, or\n  properties files. Additionally, the convert action can transform the\n  input files into translation memory tmx files. Tmx files cannot be\n  input files, only output. Note that conversion of files is not guaranteed\n  to preserve all data. For example, strings files for iOS can contain\n  comments whereas json files cannot. If you convert a strings file into a\n  json file, any comments will be lost.\n- select - Select translation units from the input xliff files based on the\n  given criteria, and write them out to an output xliff file. The selection\n  criteria allow you to specify regular expressions to match against values\n  of specific fields. Also, you can limit the output by specifying the\n  maximum number of units, or the maximum number of source or target words.\n  It also allows you to randomize the selection so you can create a sample\n  of the input translations units.\n\nCopyright and License\n-------\n\nCopyright \u0026copy; 2016-2024, HealthTap, Inc. and JEDLSoft\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this tool except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n\nSee the License for the specific language governing permissions and\nlimitations under the License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Floctool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filib-js%2Floctool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Floctool/lists"}