nativescript-l
v4.2.3
Published
Native internationalization plugin for NativeScript using native capabilities of each platform
Downloads
6
Maintainers
Readme
nativescript-l
This is a plugin for NativeScript that implements internationalization (i18n) using the native capabilities of each platform. It is a direct fork of nativescript-localize
Differences
This plugin was created to have a different behavior from nativescript-localize:
- the default
localize
method was renamed tol
- the default
l
method tries to load from a local JSON object - you can load such a JSON object with
loadLocalJSON
passing either the JSON or the path to it - if no local JSON,
l
load natively - keys are not encoded anymore, meaning keys are the same in native/js worlds.
- the locale JSON must now be a trully nested object (no
.
in keys names) - special characters support has been dropped in keys names.
Credits
A lot of thanks goes out to Eddy Verbruggen and Ludovic Fabrèges (@lfabreges) for developing and maintaining nativescript-localize.
Table of contents
Installation
tns plugin add nativescript-l
Usage
Create a folder i18n
in the app
folder with the following structure:
app
| i18n
| en.json <-- english language
| fr.default.json <-- french language (default)
| es.js
You need to set the default langage and make sure it contains the application name to avoid any error.
Angular
app.module.ts
import { NgModule, NO_ERRORS_SCHEMA } from "@angular/core";
import { NativeScriptLocalizeModule } from "nativescript-l/angular";
import { NativeScriptModule } from "nativescript-angular/nativescript.module";
import { AppComponent } from "./app.component";
@NgModule({
declarations: [AppComponent],
bootstrap: [AppComponent],
imports: [
NativeScriptModule,
NativeScriptLocalizeModule
],
schemas: [NO_ERRORS_SCHEMA]
})
export class AppModule { }
Template
<Label text="{{ 'Hello world !' | L }}"/>
<Label text="{{ 'I am %s' | L:'user name' }}"/>
Script
import { localize } from "nativescript-l";
console.log(localize("Hello world !"));
Javascript / XML
app.js
const application = require("application");
const localize = require("nativescript-l");
application.setResources({ L: localize.l });
Template
<Label text="{{ L('Hello world !') }}"/>
<Label text="{{ L('I am %s', 'user name') }}"/>
Script
const localize = require("nativescript-l");
console.log(localize("Hello world !"));
Quirks
⚠️ If you notice translations work on your main XML page, but don't work on a page you navigate to, then add this little hack to the 'page loaded' function of that new page:
const page = args.object;
page.bindingContext = new Observable();
Vue
app.js
import { l } from "nativescript-l";
Vue.filter("L", l);
Template
<Label :text="'Hello world !'|L"></Label>
<Label :text="'I am %s'|L('user name')"></Label>
File format
Each file is imported using require
, use the file format of your choice:
JSON
{
"app.name": "My app",
"ios.info.plist": {
"NSLocationWhenInUseUsageDescription": "This will be added to InfoPlist.strings"
},
"user": {
"name": "user.name",
"email": "user.email"
},
"array": [
"split the translation into ",
"multiples lines"
],
"sprintf": "format me %s",
"sprintf with numbered placeholders": "format me %2$s one more time %1$s"
}
Javascript
const i18n = {
"app.name": "My app"
};
module.exports = i18n;
Frequently asked questions
How to set the default language?
Add the .default
extension to the default language file to set it as the fallback language:
fr.default.json
How to localize the application name?
The app.name
key is used to localize the application name:
{
"app.name": "My app"
}
How to localize iOS properties?
Keys starting with ios.info.plist.
are used to localize iOS properties:
{
"ios.info.plist.NSLocationWhenInUseUsageDescription": "This will be added to InfoPlist.strings"
}
How to change the language dynamically at runtime?
Seeing this module now uses JSON objects. Overriding consist of 3 steps:
- overriding native language, done with
overrideLocaleNative
- overriding json language, done with
loadLocalJSON
- updating all labels, buttons.... your job!
import { overrideLocaleNative } from "nativescript-l/localize";
const localeOverriddenSuccessfully = overrideLocaleNative("en-GB"); // or "nl-NL", etc (or even just the part before the hyphen)
Important: In case you are using Android app bundle to release your android app, add this to App_Resources/Android/app.gradle to make sure all lanugages are bundled in the split apks
android {
// there maybe other code here //
bundle {
language {
enableSplit = false
}
}
}
Tip: you can get the default language on user's phone by using this
import { device } from '@nativescript/core/platform';
console.log("user's language is", device.language.split('-')[0]);
Tip: overrideLocaleNative method stores the language in a special key in app-settings, you can access it like this,
import { getString } from '@nativescript/core/application-settings';
console.log(getString('__app__language__')); // only available after the first time you use overrideLocaleNative(langName);
Troubleshooting
The angular localization pipe does not work when in a modal context
As a workaround, you can trigger a change detection from within your component constructor:
constructor(
private readonly params: ModalDialogParams,
private readonly changeDetectorRef: ChangeDetectorRef,
) {
setTimeout(() => this.changeDetectorRef.detectChanges(), 0);
}