i18next / i18next-android

i18next internationalization library for Android

i18next-android

i18next-android is a native Android port of i18next.

Why?

In order to use the same translated strings for the Web, Android and iOS, we decided to use the i18next features and data formats.

This library is our implementation for Android. We've been using it in production for a few years.

Download

i18next-android is available under both jCenter and Maven Central.

Grab via Gradle:

dependencies {
  compile 'com.i18next:i18next-android:1.0.0'
}

or Maven:

<dependency>
  <groupId>com.i18next</groupId>
  <artifactId>i18next-android</artifactId>
  <version>1.0.0</version>
</dependency>

---

Initialization

Instance

You can use i18next with a new instance:

I18Next i18next = new I18Next();

or with a singleton:

I18Next i18next = I18Next.getInstance();

Load data

Start by getting a Loader with:

Loader loader = i18next.loader();

After you've set the namespace, language and data, you can apply it by calling:

loader.load();

Namespace

Specifying the namespace of the file to load:

loader.namespace(String namespace)

Note: if you don't specify a namespace here, the default namespace defined in the Option is taken.

Language

Specifying the language of the file to load:

loader.lang(String lang)

Note: if you don't specify a language here, the default language of your device, or the forced language in the option if defined is taken.

Translation data

Your translations are in a JSON file. This file can be loaded in different ways:

.json file in your ressources

loader.from(Context context, int resource)

JSON string

loader.from(String json)

JSONObject

loader.from(JSONObject jsonObject)

Save and Restore previous data

You can save and restore one instance of i18next in the SharedPreferences of your Android device.

i18next.saveInPreference(SharedPreferences sharedPreference)

and

i18next.loadFromPreference(SharedPreferences sharedPreference)

Note: the options are not saved in the SharedPreferences.

---

Options

The options of i18next are accessed with:

Options options = i18next.getOptions()

You can, for example, enable debug mode (to have more logs) with:

options.setDebugMode(boolean debugMode)

You have also access to:

• default namespace
• reuse prefix and suffix
• interpolation prefix and suffix
• context prefix and suffix
• plural suffix
• namespace and key separator
• fallback language…

---

Translation features

Not all features of the javascript implementation of i18next are currently supported. Here is the list from the i18next website and how to use them with this library.

accessing resources

with default namespace

// given resourcefile translation.en.json
{
  key1: 'value of key 1'
}

Get the value with:

i18n.t("key1"); // -> value of key 1

with namespace set

// given resourcesfile namespace1.en.json (default ns)
{
   key1: 'value of key 1'
}

// given additional resourcesfile namespace2.en.json
{
  keys: {
    2: 'value of key 2',
    3: 'value of key 3'
  }
}

Get the value with:

i18n.t("key1"); // -> value of key 1
i18n.t("namespace1.key1"); // -> value of key 1
i18n.t("keys.2"); // -> missing key
i18n.t("namespace2:keys.2"); // -> value of key 2
i18n.t("namespace2:keys.3"); // -> value of key 3

using multiple keys (first found will be translated)

// given resourcefile translation.en.json
{
  key1: 'value of key 1'
}

Get the value with:

i18n.t("notExists", "key1"); // -> value of key 1

Multiline in json

// given resources in arabic
{
  'en-US': {
    translation: {
      key: [
        "line1",
        "line2",
        "line3"
      ]
    }
  }
};

This feature is not implemented in the Android library

Arrays in json

// given resources in arabic
{
  'en-US': {
    translation: {
      people: [
        { name: "tom" },
        { name: "steve" }
      ]
    }
  }
};

This feature is not implemented in the Android library

Providing a default value

// given resources
{
  'en-US': { translation: { // key not found } }
};

To get a default value if not found:

i18n.t("key", new Operation.DefaultValue("my text")); // -> my text

Nested resources

// given resources
{
  dev: { translation: { nesting1: '1 $t(nesting2)' } },
  en: { translation: { nesting2: '2 $t(nesting3)' } },
  'en-US': { translation: {  nesting3: '3' } }
};

Get the value:

i18n.t("nesting1"); // -> 1 2 3

Nested resources with option replace

// given resources
{
  en: { translation: {
    girlsAndBoys: '$t(girls, {"count": __girls__}) and __count__ boy',
    girlsAndBoys_plural: '$t(girls, {"count": __girls__}) and __count__ boys' },
    girls: '__count__ girl',
    girls_plural: '__count__ girls' } }
};

Get the value:

i18n.t("nesting1",
    new Operation.MultiPostProcessing(
        new Operation.Plural(2),
        new Operation.Interpolation("girls", "3"));
// -> 3 girls and 2 boys

Replacing variables

// given resources
{
  'en-US': { translation: {  key: '__myVar__ are important' } }
};

Get the value:

i18n.t("key", new Operation.Interpolation("myVar", "variables"));  // -> variables are important

Sprintf support

// given resources
{
  'en-US': { translation: {
    key1: 'The first 4 letters of the english alphabet are: %s, %s, %s and %s'
  }}
};

Get the value:

i18n.t("key1", new Operation.SPrintF('a', 'b', 'c', 'd'));

Simple plural

// given resources
{
  'en-US': {
    translation: {
      key: '__count__  child',
      key_plural: '__count__  children'
    }
  }
};

Get the values:

i18n.t("key", new Operation.Plural(0)); // -> 0 children
i18n.t("key", new Operation.Plural(1)); // -> 1 child
i18n.t("key", new Operation.Plural(5)); // -> 5 children

Indefinite plural

// given resources
{
  'en-US': {
    translation: {
      key: '__count__  child',
      key_plural: '__count__  children',
      key_indefinite: 'a child',
      key_plural_indefinite: 'some children'
    }
  }
};

This feature is not implemented in the Android library

Multiple plural forms

// given resources in arabic
{
  'ar': {
    translation: {
      key: 'singular',
      key_plural_0: 'zero',
      key_plural_2: 'two',
      key_plural_3: 'few',
      key_plural_11: 'many',
      key_plural_100: 'plural'
    }
  }
};

Get the value:

This feature is not implemented in the Android library

Use translation contexts

// given resources
{
  'en-US': {
    translation: {
      friend: 'A friend',
      friend_male: 'A boyfriend',
      friend_female: 'A girlfriend'
    }
  }
};

Get the value:

i18n.t("friend", new Operation.Plural(0)); // -> A friend
i18n.t("friend", new Operation.Context("male")); // -> A boyfriend
i18n.t("friend", new Operation.Context("female")); // -> A girlfriend

Credits

i18next and all its contributors.

i18next-android's Issues

Split Android code out to also support Java

🚀 Feature Proposal

Make it possible to use this library for normal Java apps.

The dependency on Android in this project seems fairly minimal so it seems like it should be possible to abstract it and offer two implementations.

Motivation

The codebase I deal with at work has a mix of web and Java desktop apps. We localise into 11 languages and currently use ICU plural formats on the Java side, which developers have a hard time dealing with.

I believe that the i18next format might make it easier to do the right thing with plurals.

Example

Similar to what's documented for the Android version, except that overloads taking Locale would be more convenient.

FUNDING.yml

I just added funding defaults to the i18next organization (so I don't have them to add everywhere). Most repos maintained by individuals already had a FUNDING.yml defined...

Feel free to add a FUNDING.yml pointing to sponsoring sources you control: https://help.github.com/en/github/building-a-strong-community/displaying-a-sponsor-button-in-your-repository