{"id":24177802,"url":"https://github.com/stefan-dimitrov/i18n-compile","last_synced_at":"2025-08-22T13:11:15.390Z","repository":{"id":57270327,"uuid":"71624334","full_name":"stefan-dimitrov/i18n-compile","owner":"stefan-dimitrov","description":"NodeJS module for assembling JSON translation files from language-merged YAML input files","archived":false,"fork":false,"pushed_at":"2018-03-26T12:03:14.000Z","size":14,"stargazers_count":4,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-10T03:54:53.849Z","etag":null,"topics":["compiled-translations","internationalization","json","nodejs","translation","yaml"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefan-dimitrov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-22T07:37:54.000Z","updated_at":"2022-01-06T06:05:17.000Z","dependencies_parsed_at":"2022-09-05T00:01:08.033Z","dependency_job_id":null,"html_url":"https://github.com/stefan-dimitrov/i18n-compile","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefan-dimitrov%2Fi18n-compile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefan-dimitrov%2Fi18n-compile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefan-dimitrov%2Fi18n-compile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefan-dimitrov%2Fi18n-compile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefan-dimitrov","download_url":"https://codeload.github.com/stefan-dimitrov/i18n-compile/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233690469,"owners_count":18714783,"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":["compiled-translations","internationalization","json","nodejs","translation","yaml"],"created_at":"2025-01-13T04:16:44.601Z","updated_at":"2025-01-13T04:16:45.186Z","avatar_url":"https://github.com/stefan-dimitrov.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# i18n-compile [![Build Status](https://travis-ci.org/stefan-dimitrov/i18n-compile.svg?branch=master)](https://travis-ci.org/stefan-dimitrov/i18n-compile)\n\nNodeJS module for assembling JSON translation files from language-merged YAML input files.\n\nOutput files are compatible with [angular-translate](https://angular-translate.github.io/) and [i18next](http://i18next.com/)\n\n## Getting Started\n\nInstallation:\n```shell\nnpm install i18n-compile --save-dev\n```\n\nUsage as a CLI executable:\n\n```sh\nUsage: i18n-compile [options] \u003cfiles...\u003e\n\n  Options:\n\n    -h, --help                output usage information\n    -o, --out \u003cdest\u003e          Output file path. May contain language placement token (--lang-place)\n    -m, --merge               Whether to merge all languages into a single file\n    -l, --lang-place [token]  Placeholder for the language name in the output file path. Only applicable if the --merge option is not used\n\n```\n\n\nUsage as a node module:\n```js\nvar i18nCompile = require('i18n-compile');\n\ni18nCompile(['src/file-1.yaml', 'src/**/*_i18n.yaml'], 'destination/path/translation_[lang].json', {langPlace: '[lang]'});\n\n// or from a string\n\nvar yamlString = ... // yaml as a string\n\nvar translations = i18nCompile.fromString(yamlString, 'src/file-1.yaml');\n// translations =\u003e {lang1: {...}, lang2: {...}, ...}\n```\n\n## The translation format\n\nThe format is inspired by [grunt-translate-compile](https://www.npmjs.com/package/grunt-translate-compile).\n\nIt is intended to greatly reduce the amount of typing needed to translate your app.\n\nThe YAML file format is used because it requires less typing compared to JSON - no need to enclose both properties and values in `\" \"`s,\nand nesting is done by indentation instead of blocks of curly braces.\n\nThe structure of the translations inside the file is like the following:\n```yaml\nMENU:\n  CART:\n    EMPTY:\n      en: Empty Cart\n      pt: Esvaziar Carrinho\n      es: Vaciar Carrito\n    CHECKOUT:\n      en: Checkout\n      pt: Fechar Pedido\n      es: Realizar Pedido\n  USER:\n    LABEL:\n      en: User\n      pt: Usuário\n      es: Usuario\n    DROPDOWN:\n      EDIT:\n        en: Edit\n        pt: Editar\n        es: Editar\n      LOGOUT:\n        en: Logout\n        pt: Sair\n        es: Finalizar la Sesión\n```\n\nNotice how the translation values are assigned directly to the language keys.\nThis way translations for all languages can be described in a single file, which eliminates the need to copy\nthe translation ids over to other files for each language that you have.\n\nThat structure reduces the size of your sources and makes your translations more manageable.\n\nCompiling the above example will result in the following output files:\n- *translation_en.json*\n  ```json\n  {\n    \"MENU\": {\n      \"CART\": {\n        \"EMPTY\": \"Empty Cart\",\n        \"CHECKOUT\": \"Checkout\"\n      },\n      \"USER\": {\n        \"LABEL\": \"User\",\n        \"DROPDOWN\": {\n          \"EDIT\": \"Edit\",\n          \"LOGOUT\": \"Logout\"\n        }\n      }\n    }\n  }\n\n  ```\n\n- *translation_pt.json*\n  ```json\n  {\n    \"MENU\": {\n      \"CART\": {\n        \"EMPTY\": \"Esvaziar Carrinho\",\n        \"CHECKOUT\": \"Fechar Pedido\"\n      },\n      \"USER\": {\n        \"LABEL\": \"Usuário\",\n        \"DROPDOWN\": {\n          \"EDIT\": \"Editar\",\n          \"LOGOUT\": \"Sair\"\n        }\n      }\n    }\n  }\n\n  ```\n\n- *translation_es.json*\n  ```json\n  {\n    \"MENU\": {\n      \"CART\": {\n        \"EMPTY\": \"Vaciar Carrito\",\n        \"CHECKOUT\": \"Realizar Pedido\"\n      },\n      \"USER\": {\n        \"LABEL\": \"Usuario\",\n        \"DROPDOWN\": {\n          \"EDIT\": \"Editar\",\n          \"LOGOUT\": \"Finalizar la Sesión\"\n        }\n      }\n    }\n  }\n\n  ```\n\n## Using the module\n\n### Arguments\n\n```\nvar i18nCompile = require('i18n-compile');\n\ni18nCompile(\u003cfile-patterns\u003e, \u003cdestination\u003e, [\u003coptions\u003e]);\n```\n\n- #### File patterns\n  Type: `Array` of `String`s\n  \n  A list of file names or [glob](https://github.com/isaacs/node-glob#glob-primer) patterns. \n  Those are the input files to be compiled.\n\n- #### Destination\n  Type: `String`\n  \n  Destination path for the compile output.\n\n- #### Options\n  Type: `Object`\n\n  #### options.langPlace\n  Type: `String`\n  Default value: `''` *(empty string)*\n  \n  If specified, and if present in the destination path, the value will be replaced with the language id.\n  For example:\n  ```\n  i18n_compile(..., 'output/path/file-[lang]-i18n.json', {langPlace: '[lang]'});\n  \n  results in output files(for languages 'en', 'bg', 'pt):\n    'output/path/file-en-i18n.json'\n    'output/path/file-bg-i18n.json'\n    'output/path/file-pt-i18n.json'\n  ```\n  \n  This option only has effect when the `merge` option is `false`.\n  \n  #### options.merge\n  Type: `Boolean`\n  Default value: `false`\n  \n  If `true` the output will be a single file with the translations for all languages merged inside it.\n\n### Usage Examples\n\n#### Default Options\nIn this example, the compiled translations for each language are written to a separate file\n\n```js\ni18nCompile(['src/**/*.yaml'], 'dest/translations-.json');\n```\nThe language id is by default inserted right before the last `.` of the file name. \u003cbr\u003e\nSo if we have the languages `en` and `bg`, the resulting files will be:\n```\ndest/translations-en.json\ndest/translations-bg.json\n```\n\nIf there is no `.` present then the language id is inserted at the end of the file name:\n```js\ni18nCompile(['src/**/*.yaml'], 'dest/translations-');\n```\n```\ndest/translations-en\ndest/translations-bg\n```\n\n#### Placement of language id\nIn this example, the language id is placed at a custom location in the output file path\n\n```js\ni18nCompile(['src/**/*.yaml'], 'dest/path/\u003clang\u003e-translations.json', {langPlace: '\u003clang\u003e'});\n```\n\nSo if we have the languages `en` and `bg`, the resulting files will be\n```\ndest/path/en-translations.json\ndest/path/bg-translations.json\n```\n\n#### Merge translations in one file\nWith `merge` set to `true` the compiled translations for all languages are merged into a single file\n\n```js\ni18nCompile(['src/**/*.yaml'], 'dest/translations.json', {merge: true});\n```\n\n## Using the `fromString` method\n\n### Arguments\n\n```\nvar i18nCompile = require('i18n-compile');\n\nvar translations = i18nCompile.fromString(\u003cinput\u003e, [\u003cfilename\u003e]);\n```\n\n- #### input\n  Type: `String`\n  \n  `yaml` content as string.\n\n- #### filename\n  Type: `String`\n  \n  File path to use when displaying errors.\n\n### Return value\n\nA javascript object mapping each language name to the translations object for that language.\n\n\n## Contributing\nIn lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefan-dimitrov%2Fi18n-compile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefan-dimitrov%2Fi18n-compile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefan-dimitrov%2Fi18n-compile/lists"}