{"id":18926778,"url":"https://github.com/ladjs/i18n","last_synced_at":"2025-04-15T13:33:20.772Z","repository":{"id":25022951,"uuid":"103001137","full_name":"ladjs/i18n","owner":"ladjs","description":"i18n wrapper and Koa middleware for Lad","archived":false,"fork":false,"pushed_at":"2023-01-08T06:51:48.000Z","size":1686,"stargazers_count":10,"open_issues_count":1,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-02T08:36:22.671Z","etag":null,"topics":["i10n","i18n","i18n2","koa","lad","locale","locales","localization","middleware","phrases","redirect","translate","translation"],"latest_commit_sha":null,"homepage":"https://lad.js.org","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/ladjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-10T03:38:49.000Z","updated_at":"2023-03-15T09:55:18.000Z","dependencies_parsed_at":"2023-01-14T01:59:45.594Z","dependency_job_id":null,"html_url":"https://github.com/ladjs/i18n","commit_stats":null,"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ladjs%2Fi18n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ladjs%2Fi18n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ladjs%2Fi18n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ladjs%2Fi18n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ladjs","download_url":"https://codeload.github.com/ladjs/i18n/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248661706,"owners_count":21141450,"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":["i10n","i18n","i18n2","koa","lad","locale","locales","localization","middleware","phrases","redirect","translate","translation"],"created_at":"2024-11-08T11:17:09.716Z","updated_at":"2025-04-15T13:33:20.435Z","avatar_url":"https://github.com/ladjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [**@ladjs/i18n**](https://github.com/ladjs/i18n)\n\n[![build status](https://github.com/ladjs/i18n/actions/workflows/ci.yml/badge.svg)](https://github.com/ladjs/i18n/actions/workflows/ci.yml)\n[![code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)\n[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n[![made with lass](https://img.shields.io/badge/made_with-lass-95CC28.svg)](https://lass.js.org)\n[![license](https://img.shields.io/github/license/ladjs/i18n.svg)]()\n\n\u003e i18n wrapper and Koa middleware for Lad\n\n\n## Table of Contents\n\n* [Install](#install)\n* [Usage](#usage)\n* [API](#api)\n  * [i18n.translate(key, locale, ...args)](#i18ntranslatekey-locale-args)\n  * [i18n.translateError(key, locale, ...args)](#i18ntranslateerrorkey-locale-args)\n  * [i18n.middleware(ctx, next)](#i18nmiddlewarectx-next)\n  * [i18n.redirect(ctx, next)](#i18nredirectctx-next)\n* [Options](#options)\n* [Redirect exceptions](#redirect-exceptions)\n* [Contributors](#contributors)\n* [License](#license)\n\n\n## Install\n\n[npm][]:\n\n```sh\nnpm install @ladjs/i18n\n```\n\n\n## Usage\n\n```js\nconst I18N = require('@ladjs/i18n');\nconst phrases = { 'HELLO': 'Hello there!' };\nconst i18n = new I18N({ phrases });\n\n// ...\n\napp.use(i18n.middleware);\napp.use(i18n.redirect);\n\n// ... routes go here ...\n\napp.listen();\n```\n\n\n## API\n\n### i18n.translate(key, locale, ...args)\n\nReturns translation for phrase `key` with the given `locale`.  Optionally pass additional arguments, e.g. format specifier replacements for use in the phrase.  For example if you have a phrase of \"An error occurred %s\" with a key of \"ERROR\\_OCCURRED\", and you use it as such `i18n.translate('ERROR_OCCURRED', 'en', 'some error message')` then it would return `'An error occurred some error message`.\n\n### i18n.translateError(key, locale, ...args)\n\nReturns the same string as `i18n.translate`, but wrapped with a new `Error` object with a property `no_translate` set to `true`.\n\nThis is an extremely useful method if you are using `koa-better-error-handler` package in the [Lad][] framework – as it will prevent a double translation from occurring.\n\n### i18n.middleware(ctx, next)\n\nThis middleware uses custom locale detection (in order of priority):\n\n1. Check URL (e.g. if `/de` or `/de/` then it's a `de` locale - as long as `de` is a supported locale)\n2. Use the custom function (if provided by the `detectLocale` parameter) for locale detection\n3. Check the `\"locale\"` cookie value (or whatever the `cookie` option is defined as)\n4. Check `Accept-Language` header\n\nIt also exposes the following:\n\n* `ctx.pathWithoutLocale` - the `ctx.path` without the locale in it (this is used by [koa-meta][])\n* `ctx.request` - with all of `i18n` API methods (e.g. `ctx.request.t`, `ctx.request.tn`, ...)\n* `ctx.locale` - set to the value of `ctx.request.locale` (the current user's locale)\n* `ctx.state` - with all of `i18n` API methods (e.g. `ctx.request.t`, `ctx.request.tn`, ...)\n* `ctx.state.l` - a shorthand method that accepts a path and returns a localized path (e.g. `ctx.state.l('/contact')` will output `/en/contact` if the locale is \"en\")\n* `ctx.state.availableLanguages` (Array) - which is useful for adding a dropdown to select from an available language\n* `ctx.state.currentLanguage` (String) - the current locale's language in native language using [country-language][]'s `getLanguage` method\n* `ctx.translate` (Function) - a helper function for calling `i18n.api.t` or `i18n.t` to translate a given phrase by its property key name from the `phrases` object option (same as `i18n.translate` except it throws a `ctx.throw` error using [Boom][])\n* `ctx.translateError` (Function) - same as `ctx.translate` except it returns an Error object with a property `no_translate` set to `true` (similar to `i18n.translateError`)\n\nIf the given locale was not available then it will redirect the user to the detected (or default/fallback) locale.\n\n### i18n.redirect(ctx, next)\n\n\u003e Inspired by [node][]'s [language support][language-support].\n\nRedirects user with permanent `302` redirect to their detected locale if a valid language was not found for them.\n\n**NOTE:** As of v1.2.2 we have added a `ignoredRedirectGlobs` option you can pass to `new I18N({ ... })` which will ignore these paths for locale redirection.  This is incredibly useful if you are using authentication providers and the `passport` library, e.g. you want to set `/auth/github/ok` as the callback URL for GitHub, but a redirect to `/en/auth/github/ok` would have occurred, thus causing authentication to fail due to a bad code.  In this case, you would set `{ ignoredRedirectGlobs: [ '/auth/**/*' ] }` or simply `[ '/auth/google/ok' ]`.  This package uses [multimatch][] internally which supports an Array, therefore you could negate certain paths if needed.  See the documentation for [multimatch][] for more insight.\n\nIt also sets the cookie `locale` for future requests to their detected locale.\n\nThis also stores the `last_locale` (or whatever you configure the property name to be in the config option `lastLocaleField`) for a user via `ctx.state.user.save()`.\n\n**NOTE:** As of v3.0.0 we have added a `redirectIgnoresNonGetMethods` (Boolean) option (defaults to `true`) which you can pass to `new I18N({ ... })` which will ignore non-GET methods on redirection.\n\n\n## Options\n\n\u003e We use [i18n][] options per \u003chttps://github.com/mashpie/i18n-node#list-of-all-configuration-options\u003e\n\nDefault options are as follows and can be overridden:\n\n```js\nconst i18n = new I18N({\n  phrases: {},\n  logger: console,\n  directory: resolve('locales'),\n  locales: ['en', 'es', 'zh'],\n  cookie: 'locale',\n  cookieOptions: {\n    // Disable signed cookies in NODE_ENV=test\n    signed: process.env.NODE_ENV !== 'test'\n  },\n  expiryMs: 31556952000, // one year in ms\n  indent: '  ',\n  defaultLocale: 'en',\n  // `process.env.I18N_SYNC_FILES`\n  syncFiles: true,\n  // `process.env.I18N_AUTO_RELOAD`\n  autoReload: false,\n  // `process.env.I18N_UPDATE_FILES`\n  updateFiles: true,\n  api: {\n    __: 't',\n    __n: 'tn',\n    __l: 'tl',\n    __h: 'th',\n    __mf: 'tmf'\n  },\n  register: i18n.api,\n  lastLocaleField: 'last_locale',\n  ignoredRedirectGlobs: [],\n  redirectIgnoresNonGetMethods: true,\n  // \u003chttps://github.com/ljharb/qs\u003e\n  stringify: {\n    addQueryPrefix: true,\n    format: 'RFC1738',\n    arrayFormat: 'indices'\n  },\n  redirectTLDS: true,\n  // function that allows using a custom logic for locale detection (can return promise)\n  detectLocale: null\n});\n```\n\nIf you wish to bind `logDebugFn`, `logWarnFn`, and `logErrorFn` per [i18n][] options:\n\n```js\nconst i18n = new I18N({\n  logDebugFn: console.log,\n  logWarnFn: console.log,\n  logErrorFn: console.log\n});\n```\n\nWe recommend to use [CabinJS][cabin] for all your logging needs.\n\nFor a list of all available locales see [i18n-locales][].\n\n\n## Redirect exceptions\n\nIf the path has an extension, then it is not redirected.\n\nHowever if `redirectTLDS` option is `true` (which is `true` by default as of v4.0.0), then if the path basename ends with a valid TLD, then it is redirected.\n\nWe came across this missing feature and added it after our discovery through [Forward Email](https://forwardemail.net).\n\n\n## Contributors\n\n| Name             | Website                           |\n| ---------------- | --------------------------------- |\n| **Nick Baugh**   | \u003chttp://niftylettuce.com/\u003e        |\n| **shadowgate15** | \u003chttps://github.com/shadowgate15\u003e |\n\n\n## License\n\n[MIT](LICENSE) © [Nick Baugh](http://niftylettuce.com/)\n\n\n##\n\n[npm]: https://www.npmjs.com/\n\n[i18n]: https://github.com/mashpie/i18n-node\n\n[i18n-locales]: https://github.com/ladjs/i18n-locales\n\n[koa-meta]: https://github.com/ladjs/koa-meta\n\n[country-language]: https://github.com/ladjs/country-language\n\n[boom]: https://github.com/hapijs/boom\n\n[node]: https://nodejs.org\n\n[language-support]: https://github.com/nodejs/nodejs.org/commit/d6cdd942a8fc0fffcf6879eca124295e95991bbc#diff-78c12f5adc1848d13b1c6f07055d996eR59\n\n[cabin]: https://cabinjs.com\n\n[multimatch]: https://github.com/sindresorhus/multimatch\n\n[lad]: https://github.com/ladjs/lad\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fladjs%2Fi18n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fladjs%2Fi18n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fladjs%2Fi18n/lists"}