{"id":15141932,"url":"https://github.com/eddyverbruggen/nativescript-localize","last_synced_at":"2025-03-30T09:32:36.836Z","repository":{"id":15970576,"uuid":"79061619","full_name":"EddyVerbruggen/nativescript-localize","owner":"EddyVerbruggen","description":"Internationalization plugin for NativeScript using native capabilities of each platform","archived":false,"fork":false,"pushed_at":"2023-07-09T03:05:49.000Z","size":3140,"stargazers_count":79,"open_issues_count":30,"forks_count":31,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-28T15:21:59.027Z","etag":null,"topics":["android","angular","i18n","internationalization","ios","javascript","l10n","nativescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/EddyVerbruggen.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":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-15T21:46:07.000Z","updated_at":"2024-05-30T15:46:21.000Z","dependencies_parsed_at":"2024-06-21T04:19:54.255Z","dependency_job_id":"03466542-6a57-4405-8c71-a2ef21624fbf","html_url":"https://github.com/EddyVerbruggen/nativescript-localize","commit_stats":null,"previous_names":["lfabreges/nativescript-localize"],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-localize","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-localize/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-localize/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-localize/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EddyVerbruggen","download_url":"https://codeload.github.com/EddyVerbruggen/nativescript-localize/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246301963,"owners_count":20755512,"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":["android","angular","i18n","internationalization","ios","javascript","l10n","nativescript"],"created_at":"2024-09-26T09:20:38.498Z","updated_at":"2025-03-30T09:32:36.818Z","avatar_url":"https://github.com/EddyVerbruggen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## NativeScript 7\n\n* Use `@nativescript/localize`: `~5.0.0`\n* [Source managed here](https://github.com/NativeScript/plugins)\n\n## If using 6 and below, see the following:\n\n# nativescript-localize\n[![npm](https://img.shields.io/npm/v/nativescript-localize.svg)](https://www.npmjs.com/package/nativescript-localize)\n[![npm](https://img.shields.io/npm/dm/nativescript-localize.svg)](https://www.npmjs.com/package/nativescript-localize)\n\nThis is a plugin for NativeScript that implements internationalization (i18n) using the native capabilities\nof each platform. It is inspired from [nativescript-i18n](https://github.com/rborn/nativescript-i18n)\n\n## Credits\nA lot of thanks goes out to [Ludovic Fabrèges (@lfabreges)](https://github.com/lfabreges) for developing and maintaining this plugin in the past. When he had to abandon it due to shifted priorities, he was kind enough to [move the repo to me](https://github.com/EddyVerbruggen/nativescript-localize/issues/73).\n\n## Table of contents\n* [Installation](#installation)\n* [Usage](#usage)\n  * [Angular](#angular)\n  * [Javascript](#javascript)\n  * [Vue](#vue)\n* [File format](#file-format)\n* [Frequently asked questions](#frequently-asked-questions)\n  * [How to set the default language?](#how-to-set-the-default-language)\n  * [How to localize the application name?](#how-to-localize-the-application-name)\n  * [How to localize iOS properties?](#how-to-localize-ios-properties)\n  * [How to change the language dynamically at runtime?](#how-to-change-the-language-dynamically-at-runtime)\n* [Troubleshooting](#troubleshooting)\n  * [The angular localization pipe does not work when in a modal context](#the-angular-localization-pipe-does-not-work-when-in-a-modal-context)\n\n## Installation\n```shell\ntns plugin add nativescript-localize\n```\n\n## Usage\nCreate a folder `i18n` in the `app` folder with the following structure:\n```\napp\n  | i18n\n      | en.json           \u003c-- english language\n      | fr.default.json   \u003c-- french language (default)\n      | es.js\n```\n\nYou need to [set the default langage](#how-to-set-the-default-language) and make sure it contains\nthe [application name](#how-to-localize-the-application-name) to avoid any error.\n\n### Angular\n#### app.module.ts\n```ts\nimport { NgModule, NO_ERRORS_SCHEMA } from \"@angular/core\";\nimport { NativeScriptLocalizeModule } from \"nativescript-localize/angular\";\nimport { NativeScriptModule } from \"nativescript-angular/nativescript.module\";\n\nimport { AppComponent } from \"./app.component\";\n\n@NgModule({\n  declarations: [AppComponent],\n  bootstrap: [AppComponent],\n  imports: [\n    NativeScriptModule,\n    NativeScriptLocalizeModule\n  ],\n  schemas: [NO_ERRORS_SCHEMA]\n})\nexport class AppModule { }\n```\n\n#### Template\n```xml\n\u003cLabel text=\"{{ 'Hello world !' | L }}\"/\u003e\n\u003cLabel text=\"{{ 'I am %s' | L:'user name' }}\"/\u003e\n```\n\n#### Script\n```ts\nimport { localize } from \"nativescript-localize\";\n\nconsole.log(localize(\"Hello world !\"));\n```\n\n### Javascript / XML\n\n#### app.js\n```js\nconst application = require(\"application\");\nconst localize = require(\"nativescript-localize\");\napplication.setResources({ L: localize });\n```\n\n#### Template\n```xml\n\u003cLabel text=\"{{ L('Hello world !') }}\"/\u003e\n\u003cLabel text=\"{{ L('I am %s', 'user name') }}\"/\u003e\n```\n\n#### Script\n```js\nconst localize = require(\"nativescript-localize\");\n\nconsole.log(localize(\"Hello world !\"));\n```\n\n#### Quirks\n⚠️ If you notice translations work on your main XML page, but don't work on a page you\nnavigate to, then add this little hack to the 'page loaded' function of that new page:\n\n```js\n  const page = args.object;\n  page.bindingContext = new Observable();\n````\n\n### Vue\n#### app.js\n```js\nimport { localize } from \"nativescript-localize\";\n\nVue.filter(\"L\", localize);\n```\n\n#### Template\n```html\n\u003cLabel :text=\"'Hello world !'|L\"\u003e\u003c/Label\u003e\n\u003cLabel :text=\"'I am %s'|L('user name')\"\u003e\u003c/Label\u003e\n```\n\n## File format\nEach file is imported using `require`, use the file format of your choice:\n\n#### JSON\n```json\n{\n  \"app.name\": \"My app\",\n  \"ios.info.plist\": {\n    \"NSLocationWhenInUseUsageDescription\": \"This will be added to InfoPlist.strings\"\n  },\n  \"user\": {\n    \"name\": \"user.name\",\n    \"email\": \"user.email\"\n  },\n  \"array\": [\n    \"split the translation into \",\n    \"multiples lines\"\n  ],\n  \"sprintf\": \"format me %s\",\n  \"sprintf with numbered placeholders\": \"format me %2$s one more time %1$s\"\n}\n```\n\n#### Javascript\n```js\nconst i18n = {\n  \"app.name\": \"My app\"\n};\n\nmodule.exports = i18n;\n```\n\n## Frequently asked questions\n### How to set the default language?\nAdd the `.default` extension to the default language file to set it as the fallback language:\n```\nfr.default.json\n```\n\n### How to localize the application name?\nThe `app.name` key is used to localize the application name:\n```json\n{\n  \"app.name\": \"My app\"\n}\n```\n\n### How to localize iOS properties?\nKeys starting with `ios.info.plist.` are used to localize iOS properties:\n```json\n{\n  \"ios.info.plist.NSLocationWhenInUseUsageDescription\": \"This will be added to InfoPlist.strings\"\n}\n```\n\n### How to change the language dynamically at runtime?\nThis plugin uses the native capabilities of each platform, language selection is therefore made by the OS.\n\n## On iOS you can programmatically override this language since plugin version 4.2.0 by doing this:\n\n```typescript\nimport { overrideLocale } from \"nativescript-localize/localize\";\nconst localeOverriddenSuccessfully = overrideLocale(\"en-GB\"); // or \"nl-NL\", etc (or even just the part before the hyphen)\n```\n\n## On Android you can programatically override this language since plugin version 4.2.1 by doing this:\n\nIn your app.ts / main.ts / app.js\n\n```ts\nimport { on, launchEvent } from '@nativescript/core/application';\nimport { androidLaunchEventLocalizationHandler } from 'nativescript-localize/localize';\n\non(launchEvent, (args) =\u003e {\n  if (args.android) {\n    androidLaunchEventLocalizationHandler();\n  }\n});\n```\n\nAnd in your settings page where user chooses the language:\n\n```ts\nimport { overrideLocale } from \"nativescript-localize/localize\";\nconst localeOverriddenSuccessfully = overrideLocale(\"en-GB\"); // or \"nl-NL\", etc (or even just the part before the hyphen)\n```\n\n\u003e **Important:** In both cases, after calling override Locale, you must ask the user to restart the app\n\nFor Example:\n\n```ts\nimport { android as _android } from '@nativescript/core/application';\nimport { overrideLocale } from 'nativescript-localize/localize';\n\nalert({\n  title: 'Switch Language',\n  message: 'The application needs to be restarted to change language',\n  okButtonText: 'Quit!'\n}).then(() =\u003e {\n  L.localize.overrideLocale(selectedLang);\n  if (isAndroid) {\n    _android.foregroundActivity.finish();\n  } else {\n    exit(0);\n  }\n});\n```\n\n\u003e **Important:** In case you are using [Android app bundle](https://docs.nativescript.org/tooling/publishing/android-app-bundle) to release your android app, add this to\n\u003e App_Resources/Android/app.gradle to make sure all lanugages are bundled in the split apks\n\n```groovy\nandroid {\n\n  // there maybe other code here //\n\n  bundle {\n    language {\n      enableSplit = false\n    }\n  }\n}\n```\n\n\u003e **Tip:** you can get the default language on user's phone by using this\n\n```ts\nimport { device } from '@nativescript/core/platform';\n\nconsole.log(\"user's language is\", device.language.split('-')[0]);\n```\n\n\u003e **Tip:** overrideLocale method stores the language in a special key in app-settings,\n\u003e you can access it like this,\n\n```ts\nimport { getString } from '@nativescript/core/application-settings'; \n\nconsole.log(getString('__app__language__')); // only available after the first time you use overrideLocale(langName);\n```\n\n## Troubleshooting\n### The angular localization pipe does not work when in a modal context\nAs a workaround, you can trigger a change detection from within your component constructor:\n```ts\nconstructor(\n  private readonly params: ModalDialogParams,\n  private readonly changeDetectorRef: ChangeDetectorRef,\n) {\n  setTimeout(() =\u003e this.changeDetectorRef.detectChanges(), 0);\n}\n```\n### Starting from Android N, there is a weird side effect while using a WebView.\nFor unknown reasons, the very first creation of it resets the application locale to the device default. Therefore, you have to set the desired locale back.\nThis is native bug and the workaround is\n```xml\n \u003cWebView url=\"https://someurl.com\" @loaded=\"webViewLoaded\"/\u003e\n```\n```javascript\nimport {overrideLocale, androidLaunchEventLocalizationHandler} from \"nativescript-localize/localize\";\nimport {getString} from '@nativescript/core/application-settings';\nconst locale = getString('__app__language__')\n\nfunction webViewLoaded(){\n    overrideLocale(locale)\n    androidLaunchEventLocalizationHandler()\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-localize","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddyverbruggen%2Fnativescript-localize","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-localize/lists"}