Update translations docs + add blog (#471)

Co-Authored-By: Franck Nijhof <git@frenck.dev>

blog/2020-04-23-frontend-translations.md

@@ -0,0 +1,18 @@
+---
+author: Paulus Schoutsen
+authorURL: https://twitter.com/balloob
+authorImageURL: /img/profile/paulus.jpg
+authorTwitter: balloob
+title: Translations for custom Lovelace
+---
+
+If you are the author of a custom Lovelace card and use translations, please pay attention as the state translation keys have changed.
+
+Before 0.109, state translations lived under `state.<domain>.<state>` or `state.<domain>.<device class>.<state>` for binary sensors. Starting with version 0.109, these translations are now part of the backend and so they have the key format for backend translations. We have standardized the state format to always include a device class. The device class `_` is reserved as a fallback for entities without a device class.
+
+| Old                                     | New                                               |
+| --------------------------------------- | ------------------------------------------------- |
+| `state.<domain>.<state>`                | `component.<domain>.state._.<state>`              |
+| `state.<domain>.<device class>.<state>` | `component.<domain>.state.<device class>.<state>` |
+
+In future releases, we're planning to migrate state attribute translations to the backend too. We'll publish this on this blog when it happens.

docs/internationalization_backend_localization.md

@@ -6,29 +6,59 @@ title: "Backend Localization"
 
 Platform translation strings are stored as JSON in the [home-assistant](https://github.com/home-assistant/home-assistant) repository. These files must be located adjacent to the component/platform they belong to. Components must have their own directory, and the file is simply named `strings.json` in that directory. For platforms, they are named `strings.<platform name>.json` in the platform directory. This file will contain the different strings that will be translatable.
 
-In order to test changes to translation files, the translation strings must be compiled into Home Assistant’s translation directories by running the following script:
+### `strings.json`
 
-```shell
+The `strings.json` contains translations for different things that the integration offers that need to be translated.
-$ python3 -m script.translations develop
+
+| Category            | Description                                       |
+| ------------------- | ------------------------------------------------- |
+| `title`             | Title of the integration.                         |
+| `state`             | States of the integration, keyed by device class. |
+| `config`            | Translations for the config flow.                 |
+| `options`           | Translations for the options flow.                |
+| `device_automation` | Translations for the device automations.          |
+
+#### Title
+
+This category is just a string: the translation of the integration name. This key is optional and Home Assistant will fallback to the integration name if it is omitted. Only include this if it's not a product brand.
+
+#### State
+
+If your integration provides entities under it's domain, you will want to translate the states. You do this by offering a `state` dictionary, that contains translations for states with different device classes. The key `_` is used for entities without a device class.
+
+```json
+{
+  "state": {
+    "problem": {
+      "off": "OK",
+      "on": "Problem"
+    },
+    "safety": {
+      "off": "Safe",
+      "on": "Unsafe"
+    },
+    "_": {
+      "off": "[%key:common::state::off%]",
+      "on": "[%key:common::state::on%]"
+    }
+  }
+}
 ```
 
-After the pull request with the strings file is merged into the `dev` branch, the strings will be automatically uploaded to Lokalise, where contributors can submit translations. The translated strings in Lokalise will be periodically pulled in to the home-assistant repository.
+#### Config / Options
-
-## States Localization
-
-The first step when localizing platform states is to ensure that the states defined in the actual platform code are defined in `snake_case`. The states should not contain capital letters or spaces. Next, the strings file needs to be created. The states should exist under the `state` key, and map the backend state keys to their English translations. [The season sensor localization](https://github.com/home-assistant/home-assistant/pull/12453/commits/bb2f328ce10c3867990e34a88da64e2f8dc7a5c4) is a good example.
-
-## Configuration Flow Localization
 
 The translation strings for the configuration flow handler are defined under the `config` key. An example strings file below describes the different supported keys:
 
 ```json
 {
   "config": {
-    "title": "This title is shown in the integrations list",
+    // Optional. Title to show in list. Only will be rendered if placeholders required
+    "flow_title": "Discovered Device ({host})",
     "step": {
       "init": {
+        // Optional. Will show the integration name if omitted
         "title": "The user visible title of the `init` step.",
+        // Optional
         "description": "Markdown that is shown with the step.",
         "data": {
           "api_key": "The label for the `api_key` input field"
@@ -44,3 +74,46 @@ The translation strings for the configuration flow handler are defined under the
   }
 }
 ```
+
+### `strings.sensor.json`
+
+Integrations can provide translations for states of its entities under other integrations like sensor. To do this, the entity will need a custom device class that starts with `<domain>__<custom name>`. You can then provide translations that will only be applied for your entity. Note that you cannot customize your translation when you use an official device class. Those are standardized.
+
+To differentiate entities and their translations, provide different device classes. The following example `strings.sensor.json` is for a Moon sensor entity with the `moon__phase` device class:
+
+```json
+{
+  "state": {
+    "moon__phase": {
+      "new_moon": "New moon",
+      "first_quarter": "First quarter",
+      "full_moon": "Full moon",
+      "last_quarter": "Last quarter"
+    }
+  }
+}
+```
+
+### Test translations
+
+In order to test changes to translation files, the translation strings must be compiled into Home Assistant’s translation directories by running the following script:
+
+```shell
+$ python3 -m script.translations develop
+```
+
+### Introducing new strings
+
+To introduce new strings, add them to `strings.json` or to a platform strings file. Try to use as many references to common strings as possible. Common strings live in `homeassistant/components/strings.json`. You can refer to those translations using references. For example:
+
+```json
+{
+  "config": {
+    "abort": {
+      "already_configured": "[%key:common.config_flow.abort.already_configured%]"
+    }
+  }
+}
+```
+
+After the pull request with the strings file is merged into the `dev` branch, the strings will be automatically uploaded to Lokalise, where contributors can submit translations. The translated strings in Lokalise will be periodically pulled in to the core repository.

docs/internationalization_custom_component_localization.md

@@ -3,10 +3,11 @@ title: "Custom Component Localization"
 ---
 
 ## Translation Strings
-Unlike localized strings merged in the `home-assistant` repository, custom components cannot take advantage of Lokalise for user submitted translations. However, custom component authors can still include translations with their components. These will be read from the `.translations` directory, adjacent to the component source. They are named `<platform name>.<language_code>.json`, e.g., for the German translation of a sensor `sensor.de.json`, unless the translation is for the custom component only, in which case the file is simply named `<language_code>.json` in the `.translations` directory.
+
+Unlike localized strings merged in the `home-assistant` repository, custom components cannot take advantage of Lokalise for user-submitted translations. However, custom component authors can still include translations with their components. These will be read from the `translations` directory, adjacent to the component source. They are named `<platform name>.<language_code>.json`, e.g., for the German translation of a sensor `sensor.de.json`, unless the translation is for the custom component only, in which case the file is named `<language_code>.json` in the `translations` directory.
 
 These files follow the same formatting as [backend translation string files](internationalization_backend_localization.md), but a copy will exist for each translated language.
 
 The language codes follow the [BCP47](https://tools.ietf.org/html/bcp47) format. The [frontend translation files](https://github.com/home-assistant/home-assistant-polymer/tree/master/translations) can also be referred to if you are unsure of the correct language code to use.
 
-The frontend will serve these files after Home Assistant is restarted.
+To make sure that your translation files are correct, test with our integration validator Hassfest. [Set up instructions here.](https://developers.home-assistant.io/blog/2020/04/16/hassfest)

docs/internationalization_index.md

@@ -8,4 +8,12 @@ Some components and platforms will have strings that need to be localized specif
 
 There are also localizable strings that exist only on the frontend. These strings are managed in the [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer) repository. These strings are stored with the frontend and don’t depend on the backend configuration.
 
+| Type              | Location |
+| ----------------- | -------- |
+| Entity states     | Core     |
+| Config flows      | Core     |
+| Options flows     | Core     |
+| Device automation | Core     |
+| Text in UI        | Frontend |
+
 Our strings are translated by the community using the online translation tool [Lokalise](https://lokalise.co/).