Internationalization

Homey Apps support internationalization so that users can use your app in their native language.

Homey Apps can store translated strings as JSON files in the /locales/ folder with the language code as filename. See these two example translation files for English and Dutch:

/locales/en.json

{
  "title": "Hello World",
  "greeting": "Hello, __name__",
  "settings": {
    "title": "My Title",
    "intro": "This is an example page."
  },
  "pair": {
    "press_button": "Press the `pair` button on your device."
  }
}

/locales/nl.json

{
  "title": "Hallo Wereld",
  "greeting": "Hallo, __name__",
  "settings": {
    "title": "Mijn Titel",
    "intro": "Dit is een voorbeeld pagina."
  },
  "pair": {
    "press_button": "Druk op de `pair` knop op jou apparaat."
  }
}

These files define translations with the ID's: title, greeting, settings.title, settings.intro, and pair.press_button. If a translated string with a certain ID is not present in the locale file for the users locale Homey will fall-back to English.

Your app's README.txt can also be translated by creating additional README.<languagecode>.txt files. For exampleREADME.nl.txt would contain the Dutch translation of the readme.

The translation object

In addition to the translation files you can define the translations directly inside the App Manifest. This is done by defining an object with the language code as keys and the translations as the values.

"title": {
  "en": "Hello, World!",
  "nl": "Hallo, wereld!"
}

You can also input a single string, when translation isn't necessary:

"title": "°C"

Always have at least an en translation! This is what Homey will fall-back on when the user language can't be found.

Temperature conversion

Your Homey app should always use Celsius internally, Homey will automatically converts capability values from Celsius to Fahrenheit. For custom capabilities make sure the "unit" is set to "°C" to let Homey know that this value should be converted.

Supported Languages

The following languages are currently supported for any Homey app.

• en: English

• nl: Dutch

• de: German

• fr: French

• it: Italian

• sv: Swedish

• no: Norwegian

• es: Spanish

• da: Danish

• ru: Russian

• pl: Polish

• ko: South Korean

Translating a string from your app

In your App, Drivers or Devices you can call this.homey.__() with the identifier of the translated string to get the translation. In the following example we define a translation with the ID title and use the translation in app.js.

/locales/en.json

{
  "title": "Hello, World!"
}

/app.js

const Homey = require('homey');

class App extends Homey.App {
  onInit() {
    console.log(this.homey.__("title")); // "Hello, World!"
  }
}

module.exports = App;

You can also use variables in your translations. In the translated string variables are surrounded by two underscores (__). To get the translated string with variables you should pass an object to this.homey.__() as the second argument with the values that you want to use for those variables.

/locales/en.json

{
  "greeting": "Hello, __name__!"
}

/app.js

const Homey = require('homey');

class App extends Homey.App {
  onInit() {
    console.log(this.homey.__("greeting", { name: "Dave" })); // "Hello, Dave!"
  }
}

module.exports = App;

Translating a string in Custom views

Within your custom views, you can also use translations. For example:

/locales/en.json

{
  "settings": {
    "title": "My Title",
    "intro": "This is an example page."
  }
}

/settings/index.html

<header class="homey-header">
  <h1 class="homey-title" data-i18n="settings.title">
    <!-- "My Title" will be placed here -->
  </h1>
  <p class="homey-subtitle" data-i18n="settings.intro">
    <!-- "This is an example page." will be placed here -->
  </p>
</header>

It is also possible to get translated strings with JavaScript:

/settings/index.html

<script type="application/javascript">
  function onHomeyReady(Homey) {
    alert(Homey.__("settings.title")); // will alert "Settings page title"
  }
</script>

To lean more about custom views you can read to the custom views guide.

Translating with OpenAI

To translate your app automatically, Homey CLI has a built-in integration that asks OpenAI to translate all .json and README.txt files. First, create an OpenAI API Key at https://platform.openai.com/api-keys and connect a payment method.

Then, execute in a command line:

$ homey app translate --api-key "..."

We found that translating an entire app usually costs less than $1.