Improved docs for the i18n project (#4796)

source/_includes/asides/developers_navigation.html

@@ -78,7 +78,14 @@
           <li>{% active_link /developers/frontend_add_more_info/ Add More Info Dialog %}</li>
           <li>{% active_link /developers/frontend_creating_custom_panels/ Add Custom Panels %}</li>
           <li>{% active_link /developers/frontend_creating_custom_ui/ Add Custom UI %}</li>
-          <li>{% active_link /developers/frontend_translation/ Translation %}</li>
+        </ul>
+      </li>
+      <li>
+        {% active_link /developers/internationalization/ Internationalization %}
+        <ul>
+          <li>{% active_link /developers/internationalization/backend_localization/ Backend Localization %}</li>
+          <li>{% active_link /developers/internationalization/custom_component_localization/ Custom Component Localization %}</li>
+          <li>{% active_link /developers/internationalization/translation/ Translation %}</li>
         </ul>
       </li>
       <li>

source/developers/internationalization/backend_localization.markdown

@@ -0,0 +1,19 @@
+---
+layout: page
+title: "Backend Localization"
+description: "Translating platforms in Home Assistant"
+date: 2018-03-01 18:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+ha_release: 0.64
+---
+
+## {% linkable_title Translation Strings %}
+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. They are named `strings.<component/platform name>.json`, unless the component being translated exists in its own directory, in which case the file is simply named `strings.json` in that directory. This file will contain the different strings that will be translatable. Currently only states are supported by the frontend.
+
+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.
+
+## {% linkable_title 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.

source/developers/internationalization/custom_component_localization.markdown

@@ -0,0 +1,20 @@
+---
+layout: page
+title: "Custom Component Localization"
+description: "Translating custom components in Home Assistant"
+date: 2018-03-01 18:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+ha_release: 0.64
+---
+
+## {% linkable_title 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 translation with their components. These will be read from the `.translations` directory, adjacent to the component source file. They are named `<component/platform name>.<language_code>.json`, unless the custom component exists in its own directory, in which case the file is simply named `<language_code>.json` in the `.translations` directory.
+
+These files follow the same formatting as [backend translation string files](/developers/internationalization/backend_localization/), 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.

source/developers/internationalization/index.markdown

@@ -0,0 +1,19 @@
+---
+layout: page
+title: "Internationalization"
+description: "Home Assistant internationalization summary"
+date: 2018-03-01 18:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+ha_release: 0.64
+---
+
+The Home Assistant internationalization project includes preparing platforms and the frontend for localization, as well as the actual translation of localized strings.
+
+Some compmonents and platforms will have strings that need to be localized specifically for that platform. These strings are managed in the core [home-assistant](https://github.com/home-assistant/home-assistant) repository. The Home Assistant backend will serve strings to the clients based on the loaded components in the running instance.
+
+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.
+
+Our strings are translated by the community using the online translation tool [Lokalise](https://lokalise.co/).

source/developers/internationalization/translation.markdown

@@ -1,13 +1,14 @@
 ---
 layout: page
-title: "Frontend Translation"
-description: "How to translate the frontend for Home Assistant."
+title: "Translation"
+description: "How to translate Home Assistant."
 date: 2017-10-27 13:00
 sidebar: true
 comments: false
 sharing: true
 footer: true
 ha_release: 0.57
+redirect_from: /developers/frontend_translation/
 ---
 
 ## {% linkable_title How to start %}