{"_id":"@aguensche/l10n","_rev":"6-da10fdfbfd2b4298e7e07ad3d70daf3b","name":"@aguensche/l10n","dist-tags":{"latest":"1.2.1"},"versions":{"1.0.0":{"name":"@aguensche/l10n","version":"1.0.0","description":"A lightweight translation library","main":"l10n.js","keywords":["internationalisation","i18n","localization","l10n","translation","translate","localize","gettext"],"repository":{"type":"git","url":"git+https://github.com/lxg/l10n.git"},"author":"","license":"MIT","gitHead":"a997b0c458c7c16661caeeb01bcb6a6532756273","bugs":{"url":"https://github.com/lxg/l10n/issues"},"homepage":"https://github.com/lxg/l10n#readme","_id":"@aguensche/l10n@1.0.0","_nodeVersion":"9.11.2","_npmVersion":"6.7.0","dist":{"integrity":"sha512-LmKRQydtgsRXCbujxY7JiJF/dE009VJk4GSQkznjc7fqUoOdehxpwVQSfLe4N2nGkCIRRt/zBdUGMg4+kO4tCg==","shasum":"2026128aa5eb14c0bd9d39ec8938a2a8c7a1edd1","tarball":"https://registry.npmjs.org/@aguensche/l10n/-/l10n-1.0.0.tgz","fileCount":2,"unpackedSize":3636,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJcZoz6CRA9TVsSAnZWagAAkegP/2XD+5l9HqKP2Hj+Gqf3\nvQIzDFrATARAxm8G7okWPp3LysIJFXVNVUyG6x//C3vZolFTV8aXxHjj7TBe\nb3UQ0mUW54xAVanREWIQD6xP0XzP6qbZni0beGV1K6KvXTjm5Jqc7K5UOisG\n9oGBNfcUgn3eLPOW7h2FdZP2k9xSa+T1efVlXEUUcHIvHNc3qR2szy/GiMcj\nHAhaddJ1IOP9zvQZfCx6CEYCxZS5oeILg2JXciljvj8EDx8gzbW1YIy8QjHb\nOTjDThdgoBTRGswqQl4m89AWoc4PbNaErbd/NafV1BG2UxVjStUWn7Yp/vVw\nx4c1FWFzNmG2EEFMk3mhrTEPAl1b8dFzh9kHb0U8Y5yko5WpvRbm16Utk4TA\nNugATDK+iWEKloqvGB68+b6sxDJDbZysRUTAN7AHXNhw8oKHcWksBbvCWFTI\n28vWEkkYO4mOyBxPEgbJRdnA3i11L2+FQC9d6W8I2CaNdIb4192n9woBDre7\nMcJPiGFxBFH7l4Fb8Z+VNKoOlAYTOFXiADSqfc9qWK0Vq4Nh+YmDJ/FKQgj5\nTk+XPE/nbx3SlaIXZspNzRHVZQkybB1obC6/cF8qeqhXmiNuAA4pMjmE5Mum\n7IJ5gg7AlBWBT/ACBQOPm2hy3+WZYGpLwrgTwtl18v4eHRtn1H/3vq/QD90q\nl/Zz\r\n=giwq\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQC4N8T4V5W7pKH5f7VFzac4cnzq5Uem+tC0V0NZsmf1sAIgP8yE7WGsEdm4hcIdZFKXEKeXbAZifx1dEvU+t+Ut4+Q="}]},"maintainers":[{"name":"aguensche","email":"account+npmjs@lxg.de"}],"_npmUser":{"name":"aguensche","email":"account+npmjs@lxg.de"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/l10n_1.0.0_1550224633859_0.10066609232836932"},"_hasShrinkwrap":false,"deprecated":"this package has been deprecated"},"1.1.0":{"name":"@aguensche/l10n","version":"1.1.0","description":"A lightweight translation library","main":"l10n.js","keywords":["internationalisation","i18n","localization","l10n","translation","translate","localize","gettext"],"repository":{"type":"git","url":"git+https://github.com/lxg/l10n.git"},"author":{"name":"Alexander Günsche"},"license":"MIT","gitHead":"b255b8515b9c6ff2c870e1ed1057c9775007dc18","bugs":{"url":"https://github.com/lxg/l10n/issues"},"homepage":"https://github.com/lxg/l10n#readme","_id":"@aguensche/l10n@1.1.0","_nodeVersion":"9.11.2","_npmVersion":"6.8.0","dist":{"integrity":"sha512-R12CO0b8VDHAKqfDAycKkCPEaQTOwi0TK7ax4I/KJ0SJ5NT6ysT1u3vkHGod6Gx6V3WSbq8pt07TRe6/rP9xwA==","shasum":"5c5325ee6406cce8deef4b1c50b134258a635617","tarball":"https://registry.npmjs.org/@aguensche/l10n/-/l10n-1.1.0.tgz","fileCount":7,"unpackedSize":14096,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJcc8EgCRA9TVsSAnZWagAAPlMP+wVri2ikkT7qwaIDd0te\nmaXR4bAGXdHXutq934d2TSdBltjt297xAy4NbGP9XYhajNIJrn/1R8UsDQ6l\nLwW3RVykSZJB+jQTOv5DbxQTMaTWEdXIGvxQhbxb7la0LumwNeqEmTwHbUyU\nxxHa3yWrHugBHs3YCvj4ufWgWd2a+I35Do5/2Brbx37/vDCaD0zKda5l9Bj5\nEApjql3G5QhNrbHNawxYiuPUok6EhE1C3J2OrFuCSLImWA0M/Szd9FzNXAZn\nDZhtQwoDE+eOtKXhuQQ8b7w8DwDlR/mV9fItZ+IZwC94pwtyfi867xR4Lljz\nUs10CnOD/NW4C11xG+D9yPBgEWX3xhcv3kMBk/csmMAM5619ThdFS/WVBQLp\nI97DOLY26h5JRdDgFTB7B0hThzTDTB23eKlkmzVkC8LlTaiW9nPXa1Y4biwy\nwi1d2ujP6oscusDAXNPpa/3YbKOuuHhJWwKdGyY1XnvcMka3jnOzM7Vyzv2Q\nh5rtoQDjDS82xrMMLkPfwdfM/ZvCIbB2k5HQ9BuXBluCeYsvHnmfnRIPzlAB\nnBIcawzQ7QCUfBiMGeGWnlBTHyjGP5ulbL5GezY0WBydbic2CDReuAaykotO\n2ghWyg2JSNqNbFt78WLkjohlwwFSvACt2saXCHDpSeGS7Tj7h1c59YfhOvpt\nNuCe\r\n=/H2P\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIAnLRgrne3ZxdcMFdb3Ln5r4J1wYXEW4Nc8Fa9KVWf11AiBi5yh3GeixkbKrQWpExwoO7Eb7Y4sMD492DBeJq0juxA=="}]},"maintainers":[{"name":"aguensche","email":"account+npmjs@lxg.de"}],"_npmUser":{"name":"aguensche","email":"account+npmjs@lxg.de"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/l10n_1.1.0_1551089951331_0.2019609004821601"},"_hasShrinkwrap":false,"deprecated":"this package has been deprecated"},"1.2.0":{"name":"@aguensche/l10n","version":"1.2.0","description":"A lightweight translation library","main":"l10n.js","keywords":["internationalisation","i18n","localization","l10n","translation","translate","localize","gettext"],"repository":{"type":"git","url":"git+https://github.com/lxg/l10n.git"},"author":{"name":"Alexander Günsche"},"license":"MIT","gitHead":"c6b53e88d5eee74840353e7e776292b13c0d8db7","bugs":{"url":"https://github.com/lxg/l10n/issues"},"homepage":"https://github.com/lxg/l10n#readme","_id":"@aguensche/l10n@1.2.0","_nodeVersion":"9.11.2","_npmVersion":"6.8.0","dist":{"integrity":"sha512-lxF7Wmhd3W5hGH4/oo7L6kaQHs+6sQ9+HvBabdYjks0105wHiAHgjIeS8PWhDimNOxX3SAFODP6yFH1cB2Hd7w==","shasum":"2d678fec403860b0eacbc4061c83b2014471333d","tarball":"https://registry.npmjs.org/@aguensche/l10n/-/l10n-1.2.0.tgz","fileCount":11,"unpackedSize":20145,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJcdA4GCRA9TVsSAnZWagAA2y4P/36NXSGklZeS9QOkQH4m\nBzdq9imht6Rw9lzvJl0I90HEMQlbJbLbXb7jayIwGkYv9CVE8SmM8s4jmKVa\ngjynY6kmijQfVYy3kSMfsohrkptxEtjZkB4aDMyV1SQwIeTOA0cV7o3IIHGm\nGPmQqpAfrJOYhjU8c7K2d1KRXJoicbPHKHHXw6qyguJqlHINarLR+uHHYSJ7\nXUKN+RIa0CU/ZdWPx1HDR/pSuuy09pwK0edYpq4QETWqShw7yF/FxEiYcKy5\nWNxWiYgyLNKcBETkvzaJsrWc5OCb+xfJ+DYIGoOi4E7HW26dc+ZI8SYLa1pQ\n+SJvgs4cKO3IZQBjbxInkdb9FAQmCmGwEU2hnNIqbU+WreliXJNXWAOIREJP\nNhQX1MJ9TbXD58j4Bzka/oJdPS71SBw0+1yOeZIlt+/4mhGmlUuhQ/E8RpHb\nSbMnkvCNYouFNvV4Gl103Shs9+SHOPO/rJyHTPQLVxlKXX2/j9qQVLHQmNYp\nMb4BjYdxAeaA9XOLBPttP40TKnNMbJNXs7kOqJh9Wi1XlhDmrXi8IILz6bPU\nOgJA3s9qDFKn7tLkxWG7WsZx0eTIDA37dnMcbS2491syhyNU88ARr7kXj+EK\ncbxG7cRdWtBWKskyoKq8Om75rUJ9ZzqPnzKm07FAd8oAR7JCiJ1blHKUPxkJ\nEM6k\r\n=UWX2\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIFwL5QnDSXc4KnI6W3VeoX6a5+h/xBz84/4fF5IbPgBdAiB8oih+7OhWCh9kr1bJynXqoFqEuQpN4MT1B5qIk6siXA=="}]},"maintainers":[{"name":"aguensche","email":"account+npmjs@lxg.de"}],"_npmUser":{"name":"aguensche","email":"account+npmjs@lxg.de"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/l10n_1.2.0_1551109637655_0.31601424407804535"},"_hasShrinkwrap":false,"deprecated":"this package has been deprecated"},"1.2.1":{"name":"@aguensche/l10n","version":"1.2.1","description":"A lightweight translation library","main":"l10n.js","keywords":["internationalisation","i18n","localization","l10n","translation","translate","localize","gettext"],"repository":{"type":"git","url":"git+https://github.com/lxg/l10n.git"},"author":{"name":"Alexander Günsche"},"license":"MIT","gitHead":"da3d0526c7ae755cfe1c7364d8fcd4c06fd9d001","bugs":{"url":"https://github.com/lxg/l10n/issues"},"homepage":"https://github.com/lxg/l10n#readme","_id":"@aguensche/l10n@1.2.1","_nodeVersion":"9.11.2","_npmVersion":"6.8.0","dist":{"integrity":"sha512-4dFAkoX1L60u5YilN3ZGT+hIbId4eg773u1zfCSrvs63i5CzSfIXKNgCN+BIZl2ugQ9TrQDkGSuarSQ4YCrvyg==","shasum":"c52b1a1a1e884f3cad3671784911b781810cc5fa","tarball":"https://registry.npmjs.org/@aguensche/l10n/-/l10n-1.2.1.tgz","fileCount":7,"unpackedSize":16948,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJcdA9qCRA9TVsSAnZWagAAghgQAISt2qCpVZxA/oPC+aSP\nKZi5X9+xlP+iNN7dVlUO89qZyji8Axf/S+no47xYm9T85PyclPvDPuLvXnkH\nhktGLwmMFbLI8WX4dc1WBgTmihndN75P8blku8UrJMoZOgkIUYHNznfAOjJJ\nB7vzxMi+bSra+OQrpnzMC6f+nj2wXWvkuymrTA8+ZNUaJQOoHuQEwi8W/3ax\njJDc7MI9RmYPodeOX43hZoQJm9QctpIWCGWOnfEnFAWQMqAMh2jpbxiuFhrQ\nh3vdhVRJebfgr9GsKVX5ujTgFp5TylRycKUxS6h5lSFYcJFfkCytz/VuAEmx\nHuKtE/c88JwlwIOlJoFR+XBvlMjPjczJjO/cLHbYg9BgfhxDQ05Oy7McBZpD\ni22h1IQh62OiIOs+buZmYJ9NeuUhtxU6NHhSRtdgjpxGqKLFMcthoQJtSpNg\nq2OhOoA3hzzNA4maYgM7uQ5RCFSwUKl0cRwca4knVWlQcygLBlfWDVyrqrt9\n50QdhgWRrmHAubxc0SDvIdGZ7ZKJ3uLj82SihnlXCgEGuDQczDbPcsyrFuvN\ngNSOCU6hlB4zkXg3d6GSwQeQLpJWLtExZTzljwXZEBuLCXkxDFcygkOlespD\noa5515z8grGZmmt7J+IYwxmAdSGmZmdySgkheyAJXX9xW9ipv0+ggibbNYNr\n4In1\r\n=X9MA\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIGkSDC3V+ICmMbIVnfMWVo/5eG1cs2qhvIGLz046mHiFAiEAn38STGlP+puXgtakSSTL+Lm87A0FEeCNvy2Ytpcs7kA="}]},"maintainers":[{"name":"aguensche","email":"account+npmjs@lxg.de"}],"_npmUser":{"name":"aguensche","email":"account+npmjs@lxg.de"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/l10n_1.2.1_1551109993869_0.09442680750816179"},"_hasShrinkwrap":false,"deprecated":"this package has been deprecated"}},"time":{"created":"2019-02-15T09:57:13.660Z","1.0.0":"2019-02-15T09:57:13.976Z","modified":"2022-04-04T12:08:48.700Z","1.1.0":"2019-02-25T10:19:11.472Z","1.2.0":"2019-02-25T15:47:17.790Z","1.2.1":"2019-02-25T15:53:14.001Z"},"maintainers":[{"email":"accounts+npm@lxg.de","name":"lxgac"},{"email":"tui@lxg.de","name":"aguensche"}],"description":"A lightweight translation library","homepage":"https://github.com/lxg/l10n#readme","keywords":["internationalisation","i18n","localization","l10n","translation","translate","localize","gettext"],"repository":{"type":"git","url":"git+https://github.com/lxg/l10n.git"},"bugs":{"url":"https://github.com/lxg/l10n/issues"},"license":"MIT","readme":"# l10n – a lightweight gettext implementation in pure ES6\n\nThis library is a lightweight implementation of the Gettext internationalisation tools. It is written in pure ES6, does not have any dependencies and is written with Web Components in mind.\n\nThe Gettext system has some nice advantages: It has great pluralisation support, it can handle message contexts, and by using the original message as catalog ID, you always have an (English) fallback, even if a given translation doesn’t exist. What’s also great is that the `.po` catalog format has very widespread industry support, so you will always find translators, tools and even auto-translate services which can work with your catalog files without knowlegde of this library or even programming at all.\n\nWhy do we need yet another JS Gettext implementation, aren’t there enough already? Here’s why:\n\n- Super small footprint: only 1.3 kB compressed/minified\n- No dependencies\n- Pure ES6: No RequireJS/CommonJS/AMD overhead\n- Large variety of pluralisation rules, especially where `n != 1` doesn’t work\n- Context-aware translations\n- Extractor harvests all translatable strings into one .po file per language\n- Support for automated translation services\n- On-the-fly locale switching\n- Automatically uses the user agent’s preferred language\n\n## Usage\n\n### Importing the library\n\n#### Pure JS\n\nThe simplest way to use this tool is to add the `l10n.js` to your project and `import` it:\n\n```js\nimport l10n from \"./l10n.js\";\n```\n\nNote that your own script must be loaded as a module (`type=\"module\"`) for this to work:\n\n```html\n<script src=\"your-script.js\" type=\"module\"></script>\n```\n\n#### NPM\n\nThis package is also available via NPM:\n\n```bash\nnpm install --save @aguensche/l10n\n```\n\nDepending on how you manage your dependencies, you must use a different path for importing. For example, with recent versions of ParcelJS, using the built-in development server, the following should work:\n\n```\nimport l10n from \"node_modules/@aguensche/l10n/l10n.js\";\n```\n\n### Translating strings\n\nThere are three translation functions you can use in your code:\n\n```js\n// The t() function simply translates a string\nl10n.t(\"Hello World!\");\n\n// The x() function scopes the message to a context. This is useful when two\n// original strings have different meanings and will most likely require\n// different translations.\n//\n// For example, in a financial context, the English word “amount” would translate\n// to the German „Betrag“, while in a context where items are counted, the German\n// translation would be „Anzahl“. Prefixing the translation with a context allows\n// translators to add both translations.\n//\n// But how do you know when to use t() or x()? The answer is: You don’t. You will\n// usually start with t() and, at some point, a translator or a user of your software\n// will inform you that there are two messages with different meanings in the target\n// language. Then you will simply fix one or both occurences in your code with the x()\n// function.\nl10n.x(\"monetary\" \"Amount\");\nl10n.x(\"item count\" \"Amount\");\n\n// The n() function is the pluralisation function. It takes three parameters: The\n// English singular, the English plural, and the actual number it refers to. The\n// function uses “pluralisation rules” to determine the correct form in the target\n// language. For example, many languages have more than two plural forms, and this\n// function will select the correct one.\n//\n// NOTE: This function will not fill in the value into the placeholder in the\n// plural form, but only return the correct message. See below for a simple\n// sprintf() implementation to do the substitution for you.\nl10n.n(\"One apple\", \"%s apples\", 4);\n```\n\n#### Simple `sprintf()` implementation\n\nTo fill the placeholders in translations, especially pluralisations, you can use something like `sprintf()`. This is not part of the l10n library, but you can use the following super-simple `sprintf()` implementation:\n\n```js\nlet sprintf = (format, ...args) => {\n    let i = 0;\n    return format.replace(/%s/g, () => args[i++]);\n};\n```\n\nThis is of course just a very basic example. You may want to use a more sophisticated implementation of `sprintf` (e.g. with support for positional parameters) in your project.\n\nUse it like this:\n\n```js\n// Simple placeholder for a name\nsprintf(l10n.t(\"Hello %s!\"), \"John Doe\");\n\n// Pluralisation. Note that you must pass the number twice: Once to n() and\n// once to sprintf()\nsprintf(l10n.n(\"One apple\", \"%s apples\", 4), 4);\n```\n\n### Switching the locale\n\nThe locale can be switched by calling the `setLocale` function. This means you can implement your own language switcher and let it trigger the locale switching. Here’s an example of a very simple switcher component:\n\n```js\nclass LocaleSwitcher extends HTMLElement\n{\n    constructor()\n    {\n        super();\n        this.shadow = this.attachShadow({ mode: 'open' });\n    }\n\n    connectedCallback()\n    {\n        this.shadow.innerHTML = `\n            <style>\n            span { cursor : pointer }\n            </style>\n            <span data-locale=\"de-DE\">🇩🇪</span>\n            <span data-locale=\"en-US\">🇬🇧</span>\n        `;\n\n        this.shadowRoot.querySelectorAll(\"span\").forEach(elem => elem.addEventListener(\n            \"click\",\n            () => l10n.setLocale(elem.getAttribute(\"data-locale\"))\n        ));\n    }\n}\n\ncustomElements.define('locale-switcher', LocaleSwitcher);\n```\n\nAfter `setLocale` has switched the locale internally, it will trigger the `l10n.locale.switch` event on the `document` element. Therefore, you can add an event listener in your element’s constructor and re-create the element.\n\n```js\ndocument.addEventListener(\"l10n.locale.switch\", () => this.connectedCallback());\n```\n\n> ATTENTION: If you have multiple nested elements, you should only trigger re-rendering on the topmost element.\n\n## The catalog manager\n\nl10n comes with a *catalog manager* which is a CLI tool and has two tasks: It extracts all translatable strings into a `.po` catalog, and it builds translation tables which you can deliver as ES6 modules to the browser.\n\nThe catalog manager needs PHP >= 7.1 and [Composer](https://getcomposer.org/) it your development environment. Why do we use PHP in a JavaScript module? Because of the great [Gettext implementation](https://github.com/oscarotero/Gettext) which provides very powerful tools for managing translations. I wasn’t able to find something similar written in JavaScript, so for now we will be using PHP.\n\n### Installing the catalog manager\n\nIf you haven’t already, install PHP and [Composer](https://getcomposer.org/). Then install the dependencies for the catalog manager.\n\n```bash\ncomposer install\n```\n\n(NOTE: We assume that Composer is installed globally and without the `.phar` extension, e.g. as `/usr/bin/composer`. Depending on your installation, you may need to adapt the path.)\n\nNow you can use the `bin/catalog` tool which is the CLI frontend to the catalog manager.\n\n### Extracting messages\n\nExtracting messages works with the `bin/catalog extract` command. It will go through all your JavaScript files, find occurences of our Gettext functions and add them to one catalog per locale. The great thing is that it will keep existing translations, so you can simply run it as often as you want.\n\n```bash\nbin/catalog extract --locale de-DE --locale fr-FR\n```\n\nThe above command will create or update the catalogs for German and French. Catalogs reside in the `./l10n` directory. So after running the command for the first time, you will find the new files `./l10n/de-DE.po` and `./l10n/fr-FR.po` in your project. Don’t forget to put them under version control.\n\nOf course, you can also specify the target languages in your `package.json` file. Simply add the `l10n` key and add a `locales` entry with an array of your locales, for example:\n\n```json\n{\n  \"l10n\" : {\n      \"locales\" : [\"de-DE\", \"fr-FR\"]\n  }\n}\n```\n\nAfter that, you can run the `catalog extract` command without parameter:\n\n```bash\nbin/catalog extract\n```\n\n### Creating the translations table\n\n**TODO**\n\n*The implementation is not ready yet, therefore documentation has to wait, too. :)*\n","readmeFilename":"README.md","author":{"name":"Alexander Günsche"}}