{"id":21314494,"url":"https://github.com/polyconseil/easygettext","last_synced_at":"2025-04-04T10:08:56.905Z","repository":{"id":2615171,"uuid":"46992632","full_name":"Polyconseil/easygettext","owner":"Polyconseil","description":"Simple gettext tokens extraction tools for HTML and Jade files.","archived":false,"fork":false,"pushed_at":"2024-02-02T10:29:55.000Z","size":1124,"stargazers_count":79,"open_issues_count":13,"forks_count":51,"subscribers_count":39,"default_branch":"master","last_synced_at":"2024-04-12T16:11:18.706Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Polyconseil.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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":"2015-11-27T17:39:28.000Z","updated_at":"2024-06-18T13:44:39.903Z","dependencies_parsed_at":"2024-06-18T13:44:29.289Z","dependency_job_id":"28a54586-b1dd-467b-8147-c426f55b4095","html_url":"https://github.com/Polyconseil/easygettext","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polyconseil%2Feasygettext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polyconseil%2Feasygettext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polyconseil%2Feasygettext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polyconseil%2Feasygettext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Polyconseil","download_url":"https://codeload.github.com/Polyconseil/easygettext/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157283,"owners_count":20893220,"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":[],"created_at":"2024-11-21T18:13:22.022Z","updated_at":"2025-04-04T10:08:56.880Z","avatar_url":"https://github.com/Polyconseil.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# easygettext\n\n[![Build Status](https://travis-ci.org/Polyconseil/easygettext.svg?branch=master)](https://travis-ci.org/Polyconseil/easygettext)\n[![codecov.io](https://codecov.io/github/Polyconseil/easygettext/coverage.svg?branch=master)](https://codecov.io/github/Polyconseil/easygettext?branch=master)\n\nRadically simple gettext tokens extraction tool for:\n\n- HTML\n- Jade/Pug\n- Javascript/ES7+\n- Vue\n- TypeScript (see [Known Issues](#known-issues))\n- Nativescript Vue with [native and web shared code](https://www.nativescript.org/vue)\n\nfiles.\n\nAlso ships with a PO-to-JSON converter.\n\n### Installation\nYou can install the [easygettext](https://www.npmjs.com/package/easygettext) package by running \n```bash\nnpm install --save-dev easygettext\n```\nor \n```bash\nyarn add --dev easygettext\n```\n\n\n### Usage \u0026 Examples\n\n#### HTML token extraction\n\nSimply invoke the tool on the templates you want to extract a POT dictionary template from.\nThe optional '--output' argument enables you to directly output to a file.\n\n```\ngettext-extract --output dictionary.pot foo.html bar.pug component.vue sourcefile.js\n```\n\n**CLI usage:**\n```\ngettext-extract [--attribute EXTRA-ATTRIBUTE] [--filterPrefix FILTER-PREFIX] [--output OUTFILE] [--parser auto|acorn|babel] \u003cFILES\u003e\n```\n\nIt recognizes the following token flavours (currently; feel free to extend it!)\n\n```html\n\u003cdiv translate\u003eHello World\u003c/div\u003e\n\n\u003cdiv translate translate-context=\"According to...\"\u003eHello World\u003c/div\u003e\n\n\u003cdiv translate translate-comment=\"My comment...\"\u003eHello World\u003c/div\u003e\n\n\u003cdiv translate translate-plural=\"Hello worlds\"\u003eHello World\u003c/div\u003e\n\n\u003cdiv placeholder=\"{{ 'Hello World' | translate }}\"\u003e\u003c/div\u003e\n\n\u003cdiv placeholder=\"{{ scopeVariable || ('Hello World' | translate) }}\"\u003e\u003c/div\u003e\n\n\u003cget-text\u003eHello World\u003c/get-text\u003e\n\n\u003ci18n\u003eHello World\u003c/i18n\u003e\n\n\u003ctranslate\u003eHello World\u003c/translate\u003e\n\n\u003c!--  The following becomes 'Broken strings are joined'  --\u003e \n\u003cspan ng-bind=\"{{ 'Broken '\n + 'strings ' +\n 'are ' + \n 'joined' |translate}}\"\u003e\u003c/span\u003e\n\n \u003cspan ng-bind=\"'Bed n\\'' + ' breakfast' |translate\"\u003e\u003c/span\u003e\n\n \u003c!-- JavaScript expressions are parsed and compiled --\u003e\n\u003cspan ng-bind=\"true ? 'Always' : 'Never' |i18n \"\u003e\u003c/span\u003e\n\n\u003c!--  By supplying the  --filterPrefix '::' parameter  --\u003e  \n\u003cspan\u003e{{:: 'Something …' |translate}}\u003c/span\u003e\n\n\u003c!--  The default delimiters '{{' and '}}' must be changed to empty strings to handle these examples  --\u003e\n\u003cspan ng-bind=\":: 'Something …' |translate\"\u003e\u003c/span\u003e\n\n\u003cdiv placeholder=\"'Hello World' | translate\"\u003e\u003c/div\u003e\n```\n\nYou can combine any context, comment and plural together. Also, you can use 'i18n' instead\nof 'translate' as master token.\n\nYou can also provide your own master tokens:\n\n```bash\ngettext-extract --attribute v-translate --output dictionary.pot foo.html bar.jade\n\ngettext-extract --attribute v-translate --attribute v-i18n --output dictionary.pot foo.html bar.jade\n\ngettext-extract --startDelimiter '[#' --endDelimiter '#]' --output dictionary.pot foo.html bar.jade\n```\n\n`gettext-extract` can also remove optional HTML whitespaces inside tags to translate (see [PR 68](https://github.com/Polyconseil/easygettext/pull/68) for more information):\n\n```\ngettext-extract --removeHTMLWhitespaces --output dictionary.pot foo.html\n```\n\n#### Supports parsing with acorn and babel\n\nIf you want to use optional-chaining, nullish-coalesce or any babel plugin, you might want to set the parameter `--parser babel`.\n\n```\ngettext-extract --parser babel --output dictionary.pot foo.html\n```\n\nIt can be set to:\n`--parser` `auto|acorn|babel`\n\nMore info at [PR 72](https://github.com/Polyconseil/easygettext/pull/72)\n\n\n#### Javascript/ES7 token extraction\n\nThe usage stays the same but with a Javascript file !\n\n```bash\ngettext-extract somefile.js\n```\n\n```javascript\n\nconst myVar = $gettext(\"My fantastic msgid\")\n\nconst myConcatVar = $gettext(\n  \"My\"\n  + \"fantastic\"\n  + \"msgid\"\n)\n\nconst myTempVar = $gettext(\n  `My\n  fantastic\n  msgid`\n)\n\nconst myContextualizedVar = $pgettext(\"some context\", \"Some other string\")\n\nconst myPluralVar = $ngettext(...)\n```\n\nWe recognize the ``$gettext``, ``$pgettext`` and ``$ngettext`` tokens as the ones from which we can extract text from.\n\nThose tokens are frozen for now, but feel free to make a pull request and add support for variable ones :)\n\nWe currently can't extract **template strings with variables** though.\n\n\n#### Extract from Vue components\n\nYou can also extract the strings marked as translatable inside the ``\u003cscript\u003e`` and ``\u003ctemplate\u003e`` sections of Vue.js components:\n\n```bash\ngettext-extract MyComponent.vue\n```\n\nWith a component that looks like this:\n\n```html\n    \u003ctemplate\u003e\n        \u003ch1\u003e{{ greeting_message }}\u003c/h1\u003e\n        \u003cp\u003e{{ number_of_people_here }}\u003c/p\u003e\n\n        \u003ch2 v-translate\u003e Some text to be translated\n    \u003c/template\u003e\n\n    \u003cscript\u003e\n        export default {\n            name: \"greetings\",\n            computed: {\n                greeting_message() {\n                    return this.$gettext(\"Hello there!\")\n                },\n                number_of_people_here(nb_folks) {\n                    return this.$ngettext(\"There is ${ n } person here.\", \"There are ${ n } persons here.\", nb_folks)\n                }\n            }\n        }\n    \u003c/script\u003e\n```\n\nThe Javascript \u0026 HTML (or Pug) extraction within a Vue component works with the same rules as stated upper in this document.\n\n\n#### Extracting from multiple files\n`gettext-extract` needs the exact file paths to work. If you want to extract gettext from all files in a folder, you can use the UNIX find command. Here is an example as a npm script:\n\n```jsonc\n{\n  //...\n  \"scripts\": {\n    // This is for VueJS files, please adapt for HTML or Jade/Pug templates\n    \"extract-gettext-cli\": \"gettext-extract --attribute v-translate --output dictionary.pot $(find scripts/src/components -type f -name '*.vue')\"\n  }\n}\n```\n\n\n#### gettext-compile\n\nOutputs or writes to an output file, the sanitized JSON version of a PO file.\n\n```bash\ngettext-compile --output translations.json fr.po en.po de.po\n```\n\n### AngularJS\nIf you use `easygettext` to extract files from an AngularJS code base, you might find the following tips helpful.\n\nTo cover the cases (1)\n```html\n\u003cinput placeholder=\"{{:: 'Insert name …' |translate }}\"\u003e\n\u003cinput placeholder=\"{{ 'Insert name …' |translate }}\"\u003e\n```\n\nand (2)\n```html\n\u003ca href=\"#\" ng-bind=\":: 'Link text' |translate\"\u003e\u003c/a\u003e\n\u003ca href=\"#\" ng-bind=\"'Link text' |translate\"\u003e\u003c/a\u003e\n\u003ca href=\"#\"\u003e{{::'Link text' |translate}}\u003c/a\u003e\n\u003ca href=\"#\"\u003e{{'Link text' |translate}}\u003c/a\u003e\n``` \nyou should run the extraction tool twice.  Once with the command-line arguments\n```bash\n--startDelimiter '{{' --endDelimiter '}}' --filterPrefix '::'\n```\nand once with the command-line arguments\n\n```bash\n--output ${html_b} --startDelimiter '' --endDelimiter '' --filterPrefix '::'\n```\n\nThe following Bash script shows how `msgcat` might help\n```bash\n#!/usr/bin/env bash\n\ninput_files=\"$(find ./src/ -iname \\*\\.html)\"\nworkdir=$(mktemp -d \"${TMPDIR:-/tmp/}$(basename $0).XXXXXXXXXXXX\") || exit 1\n\nhtml_a=${workdir}/messages-html-interpolate.pot\nhtml_b=${workdir}/messages-html.pot\n\n./dist/extract-cli.js --output ${html_a} --startDelimiter '{{' --endDelimiter '}}' --filterPrefix '::' ${input_files}\n./dist/extract-cli.js --output ${html_b} --startDelimiter '' --endDelimiter '' --filterPrefix '::' ${input_files}\n\n# Extract gettext “messages” from JavaScript files here, into ${es_a} …\nes_a=${workdir}/ecmascript.pot\n# [...] \u003e ${es_a}\n\n# Merge the different catalog templates with `msgcat`:  \nmerged_pot=${workdir}/merged.pot\nmsgcat ${html_a} ${html_b} ${es_a} \u003e ${merged_pot}\n\n# Cleanup, in case `msgcat` gave merge-conflicts in catalog header.\nheader=${workdir}/header.pot\nsed -e '/^$/q' \u003c ${html_a} \u003e ${header}\n\nbody=${workdir}/body.pot\nsed '1,/^$/d' \u003c ${merged_pot} \u003e ${body}\n\ncat ${header} ${body} \u003e ${output_file}\n\n# Remove temporary directory with working files.\nrm -r ${workdir}\n``` \nPlease note that the script needs to be modified to match your needs and environment.\n\n### Testing\n\nRun the tests using [jest](https://jestjs.io/):\n\n```bash\nnpm test\n```\n\n### Testing the CLI\n\nRun:\n\n```bash\n./src/extract-cli.js --attribute v-translate --attribute v-i18n ~/output.html\n```\n\n\n### Motivation\n\n[angular-gettext](https://angular-gettext.rocketeer.be/) is a very neat tool, that comes with Grunt tooling\nto extract translation tokens from your Pug/Jade/HTML templates and JavaScript code.\n\nUnfortunately, this has two drawbacks:\n\n- It isn't a simple command-line interface, and forces the usage of Grunt;\n- It is angular-specific.\n\nThis library comes up with two simple CLI tools to extract and compile your HTML tokens.\n\n### Why This Library?\n\nOur frontend toolchain, [systematic](https://github.com/Polyconseil/systematic) doesn't rely on Grunt/Gulp/Broccoli/...\nand uses a combination of simple Makefiles and CLI tools to do the job.\n\nThe toolchain being framework-agnostic, we don't want to depend on Angular to extract our HTML translation tokens.\nOn another note, we use the standard [xgettext](http://www.gnu.org/savannah-checkouts/gnu/gettext/manual/html_node/xgettext-Invocation.html)\ntool to extract our JavaScript translation tokens.\n\nNevertheless, the way [angular-gettext](https://angular-gettext.rocketeer.be/) does it (with tokens, directly in HTML) is elegant, is used by many other\nlibraries and will also be the way to do it in Angular2.\n\nAlso, by utilizing either [acorn](https://github.com/ternjs/acorn) or [babel](https://github.com/babel/babel), this tool will parse and compile typical JavaScript expressions used in translate-filter expressions. For example, exposed to a (AngularJS-based) fragment like\n```html\n\u003cspan ng-bind=\"isNight ? 'Moon' + 'shine' : 'Day' + 'light' |translate\"\u003e\u003c/span\u003e\n\u003cspan ng-bind=\"isC ? 'C' + (isD ? 'D' : 'd') : 'c' + (isE ? 'E' : 'e') |i18n \"\u003e\u003c/span\u003e\n``` \nwill produce the following strings\n```text\nMoonshine\nDaylight\nCD\nCd\ncE\nce\n``` \nWhich will be correctly looked up and translated during runtime, at least by [angular-gettext](https://angular-gettext.rocketeer.be/). \n\n### Known Issues\n\nTypeScript support is currently limited in that line numbers are not tracked and won't show in generated .po files. This can lead to issues with more complex translations and should be kept in mind.\n\n### Credits\n\nThanks a million to [@rubenv](https://github.com/rubenv) for the initial ideas and\nimplementations in angular-gettext-tools, which inspired me a lot.\n\nThanks to ES6 and Babel for being awesome.\n\n### Licensing\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolyconseil%2Feasygettext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolyconseil%2Feasygettext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolyconseil%2Feasygettext/lists"}