{"id":15174273,"url":"https://github.com/nextcloud-libraries/nextcloud-l10n","last_synced_at":"2025-07-30T22:04:05.281Z","repository":{"id":35142726,"uuid":"192532714","full_name":"nextcloud-libraries/nextcloud-l10n","owner":"nextcloud-libraries","description":"Nextcloud L10n helpers for apps and libraries https://npmjs.org/@nextcloud/l10n","archived":false,"fork":false,"pushed_at":"2024-10-26T01:29:58.000Z","size":5131,"stargazers_count":6,"open_issues_count":5,"forks_count":4,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-30T03:57:00.417Z","etag":null,"topics":["javascript","javascript-library","nextcloud","nextcloud-plugin","translations","typescript"],"latest_commit_sha":null,"homepage":"https://nextcloud-libraries.github.io/nextcloud-l10n/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nextcloud-libraries.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-18T12:09:07.000Z","updated_at":"2024-10-26T01:30:01.000Z","dependencies_parsed_at":"2023-12-23T03:22:29.192Z","dependency_job_id":"2b624fc8-e620-4ab0-b146-6ee8517d150e","html_url":"https://github.com/nextcloud-libraries/nextcloud-l10n","commit_stats":{"total_commits":685,"total_committers":19,"mean_commits":36.05263157894737,"dds":"0.48759124087591244","last_synced_commit":"03d07c211f7381e927955ce9fe899cdd5ccc2a26"},"previous_names":["nextcloud-libraries/nextcloud-l10n","nextcloud/nextcloud-l10n"],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud-libraries%2Fnextcloud-l10n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud-libraries%2Fnextcloud-l10n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud-libraries%2Fnextcloud-l10n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud-libraries%2Fnextcloud-l10n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nextcloud-libraries","download_url":"https://codeload.github.com/nextcloud-libraries/nextcloud-l10n/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601449,"owners_count":20964864,"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":["javascript","javascript-library","nextcloud","nextcloud-plugin","translations","typescript"],"created_at":"2024-09-27T11:42:31.963Z","updated_at":"2025-07-30T22:04:05.263Z","avatar_url":"https://github.com/nextcloud-libraries.png","language":"TypeScript","readme":"\u003c!--\n  - SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors\n  - SPDX-License-Identifier: GPL-3.0-or-later\n--\u003e\n# @nextcloud/l10n\n\n[![REUSE status](https://api.reuse.software/badge/github.com/nextcloud-libraries/nextcloud-l10n)](https://api.reuse.software/info/github.com/nextcloud-libraries/nextcloud-l10n)\n[![Test status](https://img.shields.io/github/actions/workflow/status/nextcloud-libraries/nextcloud-l10n/node-test.yml?branch=main\u0026label=tests)](https://github.com/nextcloud-libraries/nextcloud-l10n/actions/workflows/node-test.yml)\n[![npm](https://img.shields.io/npm/v/@nextcloud/l10n.svg)](https://www.npmjs.com/package/@nextcloud/l10n)\n[![Documentation](https://img.shields.io/badge/Documentation-online-brightgreen)](https://nextcloud-libraries.github.io/nextcloud-l10n/)\n\nNextcloud L10n helpers for apps and libraries.\n\n## Installation\n\n```\nnpm i -S @nextcloud/l10n\n```\n\n## Usage\n\n### With Nextcloud based translations\n\nApps normally use the Nextcloud provided translation mechanism which allows to translate backend (PHP) strings together with the frontend.\nThis can either be done using the Nextcloud Transifex automatization or translations can be done manually.\nSee the [localization docs](https://docs.nextcloud.com/server/stable/developer_manual/basics/front-end/l10n.html) for how to setup.\n\nWhen using the Nextcloud translation system (manually or with automated Transifex) Nextcloud will automatically\nregister the translations on the frontend.\nIn this case all you have to do is to import the translation functions from this package like shown below:\n\n```js\nimport { t, n } from '@nextcloud/l10n'\n// Or\nimport { translate as t, translatePlural as n } from '@nextcloud/l10n'\n```\n\n\u003e [!NOTE]\n\u003e In order to not break the l10n string extraction scripts, make sure to use the aliases `t` and `n`.\n\n#### Translate singular string\n\n```js\nt('myapp', 'Hello!')\n```\n\n#### Translate singular string with placeholders\n\n```js\nt('myapp', 'Hello {name}!', { name: 'Jane' })\n```\n\nBy default placeholders are sanitized and escaped to prevent XSS.\nBut you can disable this behavior if you trust the user input:\n\n```js\nt(\n  'myapp',\n  'See also the {linkStart}documentation{linkEnd}.',\n  {\n    linkStart: '\u003ca href=\"http://example.com\"\u003e'\n    linkEnd: '\u003c/a\u003e',\n  },\n  undefined, // this would be a number replacement\n  { escape: false },\n)\n```\n\n#### Translate plural string\n\n```js\nn('myapp', '%n cloud', '%n clouds', 100)\n```\n\nOf course also placeholders are possible:\n\n```js\nn('myapp', '{name} owns %n file', '{name} owns %n files', 100, { name: 'Jane' })\n```\n\n### Independent translation\n\nIt is also possible to use this package for Nextcloud independent translations.\nThis is mostly useful for libraries that provide translated strings.\n\nIndependent means you can use this without Nextcloud registered translations buy just providing your `.po` files.\nIf you decide to use this way you have to extract the translation strings manually, for example using the [gettext-extractor](https://github.com/lukasgeiter/gettext-extractor).\n\n```js\nimport { getGettextBuilder } from '@nextcloud/l10n/gettext'\n\nconst po = ... // Use https://github.com/smhg/gettext-parser to read and convert your .po(t) file\n\n// When using this for a Nextcloud app you can auto-detect the language\nconst gt = getGettextBuilder()\n    .detectLocale()\n    .addTranslation('sv', po)\n    .build()\n\n// But it is also possible to force a language\nconst gt = getGettextBuilder()\n    .setLocale('sv')\n    .addTranslation('sv', po)\n    .build()\n```\n\nTo make things easier you could also create aliases for this in a module and reuse it in your code:\n\n```ts\n// When using JavaScript\nexport const t = (...args) =\u003e gt.gettext(...args)\nexport const n = (...args) =\u003e gt.ngettext(...args)\n\n// When using Typescript\nexport const t = (...args: Parameters\u003ctypeof gt.gettext\u003e) =\u003e gt.gettext(...args)\nexport const n = (...args: Parameters\u003ctypeof gt.ngettext\u003e) =\u003e gt.ngettext(...args)\n```\n\n#### Translate single string\n\n```js\ngt.gettext('my source string')\n\n// or if you are using the aliases mentioned above:\nt('my source string')\n```\n\n#### Placeholders\n\n```js\ngt.gettext('this is a {placeholder}. and this is {key2}', {\n    placeholder: 'test',\n    key2: 'also a test',\n})\n```\n\n#### Translate plurals\n\n```js\ngt.ngettext('%n Mississippi', '%n Mississippi', 3)\n\n// or if you are using the aliases mentioned above:\nn('%n Mississippi', '%n Mississippi', 3)\n```\n\n## Development\n### 📤 Releasing a new version\n\n- Pull the latest changes from `main` or `stableX`\n- Checkout a new branch with the tag name (e.g `v4.0.1`): `git checkout -b v\u003cversion\u003e`\n- Run `npm version patch --no-git-tag-version` (`npm version minor --no-git-tag-version` if minor).\n  This will return a new version name, make sure it matches what you expect\n- Generate the changelog content from the [release](https://github.com/nextcloud-libraries/nextcloud-l10n/releases) page.\n  Create a draft release, select the previous tag, click `generate` then paste the content to the `CHANGELOG.md` file\n  1. adjust the links to the merged pull requests and authors so that the changelog also works outside of GitHub\n     by running `npm run prerelease:format-changelog`.\n     This will apply this regex: `by @([^ ]+) in ((https://github.com/)nextcloud-libraries/nextcloud-l10n/pull/(\\d+))`\n     Which this as the replacement: `[\\#$4]($2) \\([$1]($3$1)\\)`\n  2. use the the version as tag AND title (e.g `v4.0.1`)\n  3. add the changelog content as description (https://github.com/nextcloud-libraries/nextcloud-l10n/releases)\n- Commit, push and create PR\n- Get your PR reviewed and merged\n- Create a milestone with the follow-up version at https://github.com/nextcloud-libraries/nextcloud-l10n/milestones\n- Move all open tickets and PRs to the follow-up\n- Close the milestone of the version you release\n- Publish the previously drafted release on GitHub\n  ![image](https://user-images.githubusercontent.com/14975046/124442568-2a952500-dd7d-11eb-82a2-402f9170231a.png)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextcloud-libraries%2Fnextcloud-l10n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnextcloud-libraries%2Fnextcloud-l10n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextcloud-libraries%2Fnextcloud-l10n/lists"}