diff --git a/content/en/building/forms/app.md b/content/en/building/forms/app.md
index 440760106..3890116f7 100644
--- a/content/en/building/forms/app.md
+++ b/content/en/building/forms/app.md
@@ -376,7 +376,7 @@ The meta information in the `{form_name}.properties.json` file defines the form'
 
 | property | description | required |
 |---|---|---|
-| `title`| The form's title seen in the app. Uses a localization array using the 2-letter code, not the translation keys discussed in the [Localization section]({{< relref "building/translations/localizing-translations" >}}). | yes |
+| `title`| The form's title seen in the app. Uses a localization array using the 2-letter code, not the translation keys discussed in the [Localization section]({{< relref "building/translations/localizing" >}}). | yes |
 | `icon` | Icon associated with the form. The value is the image's key in the `resources.json` file, as described in the [Icons section]({{< relref "building/reference/resources#icons" >}}) | yes |
 | `subject_key` | Override the default report list title with a custom translation key. The translation uses a summary of the report as the evaluation context so you can include report fields in your value, for example: `Case registration {{case_id}}`. Useful properties available in the summary include: `from` (the phone number of the sender), `phone` (the phone number of the report contact), `form` (the form code), `subject.name` (the name of the subject), and `case_id` (the generated case id). Defaults to the name of the report subject. | no |
 | `hidden_fields` | Array of Strings of form fields to hide in the view report UI in the app. This is only applied to future reports and will not change how existing reports are displayed. | no |
diff --git a/content/en/building/targets/target-widgets.md b/content/en/building/targets/target-widgets.md
index b7e51adce..bbf3bb7d7 100644
--- a/content/en/building/targets/target-widgets.md
+++ b/content/en/building/targets/target-widgets.md
@@ -375,7 +375,7 @@ targets.assessments.percentage.cough.title = % Population with cough
 targets.households.with.assessments.title = Total households with assessments
 targets.households.with.gt2.assessments.title = % Household with >=2 assessments
 ```
-To upload *[translations]({{< ref "building/translations/localizing-translations#translations" >}})* to your local instance, run the following command:
+To upload *[translations]({{< ref "building/translations/localizing" >}})* to your local instance, run the following command:
 
 ```zsh
 cht --url=https://<username>:<password>@localhost --accept-self-signed-certs upload-custom-translations
diff --git a/content/en/building/translations/configuring-translations.md b/content/en/building/translations/configuring-translations.md
deleted file mode 100644
index 6363ca02a..000000000
--- a/content/en/building/translations/configuring-translations.md
+++ /dev/null
@@ -1,337 +0,0 @@
----
-title: Configuring
-linkTitle: Configuring
-weight: 2
-description: >
- Localizing language in the CHT
-relatedContent: >
-  building/translations/managing-translations
-  building/translations/localizing-translations
-aliases:
-   - /building/tutorials/localizing-cht
-   - /apps/tutorials/localizing-cht
----
-
-{{% pageinfo %}}
-
-This section will take you through localizing the CHT to a custom language (Swahili). This will include setting up the user interface labels as well as outgoing text messages.
-
-By the end of the section you should be able to:
-
-- Change the CHT user interface labels to a custom language.
-- Change outgoing text messages to a custom language(Swahili will be used in the guide).
-{{% /pageinfo %}}
-
-## Configuration Steps
-
-Create a new file in the 'translations/' folder called `messages-sw.properties`.
-
-After an edit or addition of a translation, upload the current `messages-sw.properties` onto your local environment using the below command.
-
-```
-cht --url=https://medic:password@localhost --upload-custom-translations
-```
-
-### 1. Add User Interface Label Translations
-_**CHT Instance text**_ - for non-admin users, this is the text that falls under **Messages**, **Tasks**, **Reports**, **People** and **Targets**.
-To localize instance text to Swahili, change the default system language to `Swahili`.
-
-<br clear="all">
-
-{{< figure src="change-system-language.png" link="change-system-language.png" class="right col-6 col-lg-8" >}}
-
-Go to App Management > Display > Languages > Default Language(Change to Swahili)
-
-<br clear="all">
-
-{{< figure src="click-language-name.png" link="click-language-name.png" class="right col-6 col-lg-8" >}}
-
-To find out what the language code for Swahili is, Go to the list of language as illustrated in the screenshot, click `Kiswahili (Swahili)` to show the options dropdown and click `Edit Name` the code will be in the text box under `Language Code` on the popup. 
-
-<br clear="all">
-
-{{< figure src="click-language-edit-name-popup.png" link="click-language-edit-name-popup.png" class="right col-6 col-lg-8" >}}
-
-In our case, the language code is `sw`.
-
-<br clear="all">
-
-Create a `message-sw.properties` file and use the instructions outlined [here]({{< ref "building/translations/localizing-translations#translations" >}}) to learn the structure of a message-{language-code}.properties file.
-
-Populate the `messages-sw.properties` file with the appropriate translation strigs and upload it using the below command:
-
-```
-cht --local upload-custom-translations
-```
-The default Swahili translations that come pre-added to CHT can be found [here](https://github.com/medic/cht-core/blob/4.5.x/config/standard/translations/messages-sw.properties).
-
-After changing the instance language to Swahili, the various elements will behave like this:
-
-_**Messages**_
-
-In Messages, the time counter text and navigation text changes.
-
-This is an example of Swahili localization.
-
-<br clear="all">
-
-{{< figure src="messages-tab-language-en.png" link="messages-tab-language-en.png" class="right col-6 col-lg-8" >}}
-
-*English text*
-
-<br clear="all">
-
-{{< figure src="messages-tab-language-sw.png" link="messages-tab-language-sw.png" class="right col-6 col-lg-8" >}}
-
-*Swahili Translation*
-
-<br clear="all">
-
-To change the title of the tab from the default title of this _Messages_ tab of `Jumbe` in Kiswahili to `Barua`, add or edit the below code in the `messages-sw.properties` file:
-
-```
-Messages = Jumbe
-```
-to 
-
-```
-Messages = Barua
-```
-
-_**Tasks**_
-
-Localize the task header by adding the appropriate translation in the `messages-sw.properties` file.
-
-For example, to translate the below delivery task title to Swahili:
-
-```
-{
-    name: 'anc-home-visit-delivery',
-    icon: 'icon-pregnancy',
-    title: 'task.anc.delivery.title',
-``` 
-
-Add the code below to the `messages-sw.properties` file
-```
-task.anc.delivery.title = Kazi ya Kujifungua
-```
-<br clear="all">
-
-{{< figure src="localize-tasks-en.png" link="localize-tasks-en.png" class="right col-6 col-lg-8" >}}
-
-*Default English  text*
-
-<br clear="all">
-
-{{< figure src="localize-tasks-sw.png" link="localize-tasks-sw.png" class="right col-6 col-lg-8" >}}
-
-*Swahili translation*
-
-<br clear="all">
-
-To change the title of the tab from the default title of this _Tasks_ tab of `Kazi` in Kiswahili to `Fanya Hizi`, add or edit the below code in the `messages-sw.properties` file:
-
-```
-Tasks = Kazi
-```
-to 
-
-```
-Tasks = Fanya Hizi
-```
-
-_**Reports**_
-
-Localize the report field names by adding the appropriate translation in the `messages-{language-code}.properties` file.
-
-For example, to change the date of birth field to Swahili, in `messages-sw.properties` file, add this:
-
-```
-contact.type.date_of_birth = Siku ya Kuzaliwa
-```
-
-<br clear="all">
-
-{{< figure src="localize-reports-en.png" link="localize-reports-en.png" class="right col-6 col-lg-8" >}}
-
-*Before*
-
-<br clear="all">
-
-{{< figure src="localize-reports-sw.png" link="localize-reports-sw.png" class="right col-6 col-lg-8" >}}
-
-*Swahili Translation*
-
-<br clear="all">
-
-To change the title of the tab from the default title of this _Reports_ tab of `Ripoti` in Kiswahili to `Ripoti hizi`, add or edit the below code in the `messages-sw.properties` file.
-
-```
-Reports = Ripoti hizi
-```
-to 
-
-```
-Reports = Ripoti hizi
-```
-
-e.g 
-
-_**People**_
-
-To localize the contact labels, add the appropriate translation in `messages-{language-code}.properties` file.
-
-e.g to change the people name label translation from the default Swahili translation of `Watu` to `Watu wa hili hapa eneo`, in `messages-sw.properties` file, add this:
-
-```
-contact.type.person = Mtu wa hili hapa eneo
-contact.type.person.plural = Watu wa hili hapa eneo
-```
-<br clear="all">
-
-{{< figure src="people-translation-en.png" link="people-translation-en.png" class="right col-6 col-lg-8" >}}
-
-*Before*
-
-<br clear="all">
-
-{{< figure src="people-translation-sw.png" link="people-translation-sw.png" class="right col-6 col-lg-8" >}}
-
-*After
-
-<br clear="all">
-
-To change the title of the tab from the default title of this _People_ tab of `Wasiliani` in Kiswahili to `Watu`, add or edit the below code in the `messages-sw.properties` file.
-
-```
-People = Wasiliani
-```
-to 
-
-```
-People = Watu
-```
-
-_**Targets**_
-
-You can localize the names of the targets by adding the appropriate translation in the `messages-{language-code}.properties file.
-
-For example, to add the `Growth Monitoring` target title in Swahili on the instance, add the appropriate translation in the `messages-sw.properties` file. For instance:
-
-```
-targets.growth_monitoring.title = Ufuatiliaji wa ukuaji
-```
-<br clear="all">
-
-{{< figure src="growth-monitoring-before.png" link="growth-monitoring-before.png" class="right col-6 col-lg-8" >}}
-
-
-*Before adding the Swahili target label*
-
-<br clear="all">
-
-{{< figure src="growth-monitoring-after.png" link="growth-monitoring-after.png" class="right col-6 col-lg-8" >}}
-
-*After adding the Swahili target label*
-
-<br clear="all">
-
-To change the title of the tab from the default title of this _Targets_ tab of `Grafu` in Kiswahili to `Lengo`, add or edit the below code in the `messages-sw.properties` file.
-
-```
-Targets = Grafu
-```
-to 
-
-```
-Targets = Lengo
-```
-
-### 2. App Forms
-To localize an app form to Swahili, open the appropriate xlsx of the form and add a `label::sw` column which has the translation for the text. This will work in the `Survey` sheet or the `choices` sheet.
-
-<br clear="all">
-
-{{< figure src="new-person-xls-form.png" link="new-person-xls-form.png" class="right col-6 col-lg-8" >}}
-
-*New Person app form XLS configuration*
-
-<br clear="all">
-
-{{< figure src="new-person-form-english.png" link="new-person-form-english.png" class="right col-6 col-lg-8" >}}
-
-*Screenshot of default English translation*
-
-<br clear="all">
-
-{{< figure src="new-person-form-swahili.png" link="new-person-form-swahili.png" class="right col-6 col-lg-8" >}}
-
-*Screenshot of form after switching CHV language to Kiswahili*
-
-<br clear="all">
-
-_**App Management - Admin Area**_
-This will still remain in English even after changing the default language to Swahili.
-
-
-
-{{% alert title="Note" %}}The CHV can also choose the language of their choice when they login for the first time. A popup appears where they can choose their preferred language.
-{{% /alert %}} 
-### 3. Outgoing Texts
-
-These are the SMS notifications/replies that go to CHVs and Supervisors phones in projects that incorporate SMS workflows.
-
-To change the language of outgoing texts to a particular CHV/Supervisor to Swahili: 
-
-First in the `app_settings.json`, when configuring replies, add Swahili(sw) under `locales`:
-```
-"locales": [
-    {
-      "code": "en",
-      "name": "English"
-    },
-    {
-      "code": "es",
-      "name": "Spanish"
-    },
-    {
-      "code": "fr",
-      "name": "French"
-    },
-    {
-      "code": "ne",
-      "name": "Nepali"
-    },
-    {
-      "code": "sw",
-      "name": "Swahili"
-    }
-``` 
-
-Set up the translation for the reply message:
-```
-"messages": [{
-		"message": [{
-				"content": "Thank you, visit for {{patient_name}} ({{patient_id}}) has been recorded.",
-				"locale": "en"
-			},
-			{
-				"content": "Asante, kuhudhuria kwa {{patient_name}} ({{patient_id}} kumerekodiwa.",
-				"locale": "sw"
-			}
-		],
-		"event_type": "report_accepted",
-		"recipient": "reporting_unit"
-	}
-```
-<br clear="all">
-
-{{< figure src="change-user-language.png" link="change-user-language.png" class="right col-6 col-lg-8" >}}
-
-Change the CHVs language by following: App Management > Users > [Choose CHV username e.g chv_1] > Language > Pick Swahili:
-
-<br clear="all">
-
-### Translating CHT to another language
-
-To translate CHT to a new language (we have English, French, Hindi, Nepali, Spanish, Swahili, and Indonesian already in CHT), follow the steps outlined [here]({{< ref "building/translations/managing-translations" >}}) for reference.
\ No newline at end of file
diff --git a/content/en/building/translations/localizing-translations.md b/content/en/building/translations/localizing-translations.md
deleted file mode 100644
index 15d3a1b2d..000000000
--- a/content/en/building/translations/localizing-translations.md
+++ /dev/null
@@ -1,58 +0,0 @@
----
-title: Localizing
-linkTitle: Localizing
-weight: 3
-description: >
-  Localization for CHT applications
-keywords: localization languages translations
-aliases:
-   - /building/reference/translations
-   - /apps/reference/translations
----
-
-Given that CHT apps are used around the world, the Core Framework was designed with localization in mind. The Core Framework itself is available in English, French, Hindi, Nepali, Spanish, Swahili, and Indonesian.  
-In the `app_settings.json` file the default language for the application is set by the `locale` property, along with a separate default language for outgoing messages that are sent via SMS with the `locale_outgoing` property.  
-Additionally, languages available to the user can be enabled and disabled through the `languages` property which contains an array of objects. These objects should contain the `locale` and `enabled` properties representing respectively the 2 or 3 letter language code and whether that language should be enabled.
-
-
-{{% alert title="Note" color="info" %}}
-Please open [an issue](https://github.com/medic/cht-core/issues/new) if you are interested in translating the app into a different language, as we can work together to make that language available to the community.
-{{% /alert %}}
-
-## Translations
-
-To modify some labels in the app add the key and modified label in a custom translations file in the `translations` folder. All the properties files use the format `messages-{language-code}.properties`, where the language code is the same 2-letter code used to identify the language in the application. For instance, for English, we would have a `translations/messages-en.properties` file. 
-
-New elements in CHT apps, such as tasks, targets, profiles, and forms should be localized as well. These labels should be included in the same custom translations properties file. If a translation is missing for the user's language it will use that of the default language. 
-
-Here is an example, including both a modified label, and a new one:
-
-### `translations/messages-{language-code}.properties`
-
-```
-    [Application Text]
-    contact.type.district_hospital = Community
-    targets.assessments.title = Assessments Completed
-```
-
-## Forms
-
-Translations for XForms are defined within the forms themselves. The XLSForm notation is [documented here](http://xlsform.org/en/#multiple-language-support), and would use the corresponding 2-character language codes.
-
-## Reports
-
-Submitted forms are shown on the Reports tab, with each value in the report displayed alongside a label. The label for each value is represented by a key in the `report.{form-name}.{field-name}` format, which can be translated by including the key and translation in the [language files]( {{< relref "#translations" >}} ). If the label is omitted in the translation the full key will show in the app.
-
-{{% alert title="Note" color="info" %}}
-To hide report fields from showing on the Reports view altogether, the containing group or field must be included as `hidden_fields`, as per the [form properties file]( {{< ref "building/forms/app#properties" >}} ).
-{{% /alert %}}
-
-## Build
-
-Custom translations from the properties files are added to the app with the `upload-custom-translations` action.
-
-`cht --local upload-custom-translations`
-    
-Updated translations from forms need to be added with the actions to upload forms.
-
-`cht --local upload-contact-forms upload-app-forms`
diff --git a/content/en/building/translations/localizing.md b/content/en/building/translations/localizing.md
new file mode 100644
index 000000000..97fc64aba
--- /dev/null
+++ b/content/en/building/translations/localizing.md
@@ -0,0 +1,349 @@
+---
+title: Localizing the CHT
+linkTitle: Localizing
+weight: 2
+description: >
+  Using the CHT in the desired language
+relatedContent: >
+  building/translations/managing
+aliases:
+   - /building/tutorials/localizing-cht
+   - /apps/tutorials/localizing-cht
+   - /building/translations/localizing-translations
+   - /building/translations/configuring-translations
+---
+
+{{% pageinfo %}}
+This section will take you through localizing the CHT to a custom language (in this guide, Swahili). This will include setting up the user interface labels as well as outgoing text messages.
+
+By the end of the section you should be able to:
+
+- Change the CHT user interface labels to a custom language.
+- Change outgoing text messages to a custom language (Swahili).
+{{% /pageinfo %}}
+
+## Prerequisites
+
+- A local CHT instance [with `cht-conf` installed locally]({{< ref "building/local-setup" >}})
+- A [project folder]({{< ref "building/local-setup#3-create-and-upload-a-blank-project" >}})
+- CHT Swahili translations in a `messages-sw.properties` file.
+
+## Localization Steps
+
+Create a `messages-sw.properties` file by using [these instructions]({{< ref "building/translations/managing" >}}).
+
+Populate the `messages-sw.properties` file with the appropriate translation and upload it onto your local CHT environment using the command below.
+
+```shell
+cht --url=https://medic:password@localhost --upload-custom-translations
+```
+
+or simply:
+
+```shell
+cht --local upload-custom-translations
+```
+
+### 1. Add User Interface Label Translations
+
+For non-admin users, CHT Instance text refers to the text that falls under **Messages**, **Tasks**, **Reports**, **People** and **Targets**. 
+To localize instance text to Swahili, change the default system language to `Swahili`.
+
+<br clear="all">
+
+{{< figure src="change-system-language.png" link="change-system-language.png" class="right col-6 col-lg-8" >}}
+
+Go to App Management > Display > Languages > Default Language(Change to Swahili)
+
+<br clear="all">
+
+{{< figure src="click-language-name.png" link="click-language-name.png" class="right col-6 col-lg-8" >}}
+
+To find out what the language code for Swahili is, go to the list of languages as illustrated in the screenshot, click `Kiswahili (Swahili)` to show the options dropdown and click `Edit Name`. The code will be in the text box under `Language Code` on the popup. 
+
+<br clear="all">
+
+{{< figure src="click-language-edit-name-popup.png" link="click-language-edit-name-popup.png" class="right col-6 col-lg-8" >}}
+
+For this example, the language code is `sw`.
+
+<br clear="all">
+
+After changing the CHT instance language to Swahili, the various elements will behave like this:
+
+##### Messages
+
+In the Messages tab, the time counter text and navigation text changes, as in the screenshots below.
+
+<br clear="all">
+
+{{< figure src="messages-tab-language-en.png" link="messages-tab-language-en.png" class="right col-6 col-lg-8" >}}
+
+*In English*
+
+<br clear="all">
+
+{{< figure src="messages-tab-language-sw.png" link="messages-tab-language-sw.png" class="right col-6 col-lg-8" >}}
+
+*In Swahili*
+
+<br clear="all">
+
+To change the title of the tab from the default title of the _Messages_ tab from `Jumbe` in Kiswahili to `Barua`, add or edit the below value in the `messages-sw.properties` file:
+
+```
+Messages = Jumbe
+```
+to 
+
+```
+Messages = Barua
+```
+
+##### Tasks
+
+Localize the Tasks header by adding the appropriate translation in the `messages-sw.properties` file.
+
+For example, to translate the below delivery task title to Swahili:
+
+```
+{
+    name: 'anc-home-visit-delivery',
+    icon: 'icon-pregnancy',
+    title: 'task.anc.delivery.title',
+}
+``` 
+
+Add the value below to the `messages-sw.properties` file:
+
+```
+task.anc.delivery.title = Kazi ya Kujifungua
+```
+<br clear="all">
+
+{{< figure src="localize-tasks-en.png" link="localize-tasks-en.png" class="right col-6 col-lg-8" >}}
+
+*In English*
+
+<br clear="all">
+
+{{< figure src="localize-tasks-sw.png" link="localize-tasks-sw.png" class="right col-6 col-lg-8" >}}
+
+*In Swahili*
+
+<br clear="all">
+
+To change the title of the tab from the default title of the _Tasks_ tab from `Kazi` in Kiswahili to `Fanya Hizi`, add or edit the below code in the `messages-sw.properties` file:
+
+```
+Tasks = Kazi
+```
+
+to 
+
+```
+Tasks = Fanya Hizi
+```
+
+##### Reports
+
+Localize the Reports tab field names by adding the appropriate translations in the `messages-sw.properties` file.
+
+For example, to change the date of birth field to Swahili, in `messages-sw.properties` file, add this:
+
+```
+contact.type.date_of_birth = Siku ya Kuzaliwa
+```
+
+<br clear="all">
+
+{{< figure src="localize-reports-en.png" link="localize-reports-en.png" class="right col-6 col-lg-8" >}}
+
+*In English*
+
+<br clear="all">
+
+{{< figure src="localize-reports-sw.png" link="localize-reports-sw.png" class="right col-6 col-lg-8" >}}
+
+*In Swahili*
+
+<br clear="all">
+
+To change the title of the tab from the default title of the _Reports_ tab from `Ripoti` in Kiswahili to `Ripoti hizi`, add or edit the below code in the `messages-sw.properties` file.
+
+```
+Reports = Ripoti
+```
+
+to 
+
+```
+Reports = Ripoti hizi
+```
+
+##### People
+
+To localize the People tab labels, add the appropriate translation in `messages-sw.properties` file.
+
+To change the people name label translation from the default Swahili translation of `Watu` to `Watu wa hili hapa eneo`, in `messages-sw.properties` file, add the following values:
+
+```
+contact.type.person = Mtu wa hili hapa eneo
+contact.type.person.plural = Watu wa hili hapa eneo
+```
+
+<br clear="all">
+
+{{< figure src="people-translation-en.png" link="people-translation-en.png" class="right col-6 col-lg-8" >}}
+
+*In English*
+
+<br clear="all">
+
+{{< figure src="people-translation-sw.png" link="people-translation-sw.png" class="right col-6 col-lg-8" >}}
+
+*In Swahili*
+
+<br clear="all">
+
+To change the title of the _People_ tab from `Wasiliani` in Kiswahili to `Watu`, add or edit the below code in the `messages-sw.properties` file.
+
+```
+People = Wasiliani
+```
+
+to 
+
+```
+People = Watu
+```
+
+##### Targets
+
+To localize the People tab labels, add the appropriate translation in `messages-sw.properties` file.
+
+To add the `Growth Monitoring` target title in Swahili, add the appropriate translation in the `messages-sw.properties` file.
+
+```
+targets.growth_monitoring.title = Ufuatiliaji wa ukuaji
+```
+
+<br clear="all">
+
+{{< figure src="growth-monitoring-before.png" link="growth-monitoring-before.png" class="right col-6 col-lg-8" >}}
+
+*Before*
+
+<br clear="all">
+
+{{< figure src="growth-monitoring-after.png" link="growth-monitoring-after.png" class="right col-6 col-lg-8" >}}
+
+*In Swahili*
+
+<br clear="all">
+
+To change the title of the _Targets_ tab from `Grafu` in Kiswahili to `Lengo`, add or edit the below code in the `messages-sw.properties` file.
+
+```
+Targets = Grafu
+```
+
+to 
+
+```
+Targets = Lengo
+```
+
+### 2. App Forms
+
+To localize a CHT app form to Swahili, open the appropriate xlsx of the form and add a `label::sw` column which has the translation for the text. This will work in the `Survey` sheet or the `choices` sheet.
+
+<br clear="all">
+
+{{< figure src="new-person-xls-form.png" link="new-person-xls-form.png" class="right col-6 col-lg-8" >}}
+
+*New Person app form XLS configuration*
+
+<br clear="all">
+
+{{< figure src="new-person-form-english.png" link="new-person-form-english.png" class="right col-6 col-lg-8" >}}
+
+*Default English translation*
+
+<br clear="all">
+
+{{< figure src="new-person-form-swahili.png" link="new-person-form-swahili.png" class="right col-6 col-lg-8" >}}
+
+*Form after switching CHV's language to Kiswahili*
+
+<br clear="all">
+
+The _App Management - Admin Area_ section will still remain in English even after changing the default language to Swahili.
+
+{{% alert title="Note" %}}
+The CHV can also choose the language of their choice when they login for the first time. A popup appears where they can choose their preferred language.
+{{% /alert %}} 
+
+### 3. Outgoing Texts
+
+In projects that incorporate SMS workflows, there are SMS notifications/replies that go to CHVs and Supervisors phones.
+
+To change the language of outgoing texts for a CHV or Supervisor to Swahili, follow the steps below.
+
+- In the `app_settings.json`, when configuring replies, add Swahili language code (sw) under `locales`:
+
+```json
+"locales": [
+    {
+      "code": "en",
+      "name": "English"
+    },
+    {
+      "code": "es",
+      "name": "Spanish"
+    },
+    {
+      "code": "fr",
+      "name": "French"
+    },
+    {
+      "code": "ne",
+      "name": "Nepali"
+    },
+    {
+      "code": "sw",
+      "name": "Swahili"
+    }
+]
+``` 
+
+- Set up the translation for the reply message:
+
+```json
+{
+  "messages":[
+    {
+      "message":[
+        {
+          "content":"Thank you, visit for {{patient_name}} ({{patient_id}}) has been recorded.",
+          "locale":"en"
+        },
+        {
+          "content":"Asante, kuhudhuria kwa {{patient_name}} ({{patient_id}} kumerekodiwa.",
+          "locale":"sw"
+        }
+      ],
+      "event_type":"report_accepted",
+      "recipient":"reporting_unit"
+    }
+  ]
+}
+```
+
+<br clear="all">
+
+{{< figure src="change-user-language.png" link="change-user-language.png" class="right col-6 col-lg-8" >}}
+
+Change the CHVs language via: App Management > Users > [Choose CHV username e.g chv_1] > Language > Pick Swahili:
+
+<br clear="all">
diff --git a/content/en/building/translations/configuring-translations/app-forms-localization.png b/content/en/building/translations/localizing/app-forms-localization.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/app-forms-localization.png
rename to content/en/building/translations/localizing/app-forms-localization.png
diff --git a/content/en/building/translations/configuring-translations/change-system-language.png b/content/en/building/translations/localizing/change-system-language.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/change-system-language.png
rename to content/en/building/translations/localizing/change-system-language.png
diff --git a/content/en/building/translations/configuring-translations/change-user-language.png b/content/en/building/translations/localizing/change-user-language.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/change-user-language.png
rename to content/en/building/translations/localizing/change-user-language.png
diff --git a/content/en/building/translations/configuring-translations/click-language-edit-name-popup.png b/content/en/building/translations/localizing/click-language-edit-name-popup.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/click-language-edit-name-popup.png
rename to content/en/building/translations/localizing/click-language-edit-name-popup.png
diff --git a/content/en/building/translations/configuring-translations/click-language-name.png b/content/en/building/translations/localizing/click-language-name.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/click-language-name.png
rename to content/en/building/translations/localizing/click-language-name.png
diff --git a/content/en/building/translations/configuring-translations/growth-monitoring-after.png b/content/en/building/translations/localizing/growth-monitoring-after.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/growth-monitoring-after.png
rename to content/en/building/translations/localizing/growth-monitoring-after.png
diff --git a/content/en/building/translations/configuring-translations/growth-monitoring-before.png b/content/en/building/translations/localizing/growth-monitoring-before.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/growth-monitoring-before.png
rename to content/en/building/translations/localizing/growth-monitoring-before.png
diff --git a/content/en/building/translations/configuring-translations/localize-reports-en.png b/content/en/building/translations/localizing/localize-reports-en.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/localize-reports-en.png
rename to content/en/building/translations/localizing/localize-reports-en.png
diff --git a/content/en/building/translations/configuring-translations/localize-reports-sw.png b/content/en/building/translations/localizing/localize-reports-sw.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/localize-reports-sw.png
rename to content/en/building/translations/localizing/localize-reports-sw.png
diff --git a/content/en/building/translations/configuring-translations/localize-tasks-en.png b/content/en/building/translations/localizing/localize-tasks-en.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/localize-tasks-en.png
rename to content/en/building/translations/localizing/localize-tasks-en.png
diff --git a/content/en/building/translations/configuring-translations/localize-tasks-sw.png b/content/en/building/translations/localizing/localize-tasks-sw.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/localize-tasks-sw.png
rename to content/en/building/translations/localizing/localize-tasks-sw.png
diff --git a/content/en/building/translations/configuring-translations/messages-tab-language-en.png b/content/en/building/translations/localizing/messages-tab-language-en.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/messages-tab-language-en.png
rename to content/en/building/translations/localizing/messages-tab-language-en.png
diff --git a/content/en/building/translations/configuring-translations/messages-tab-language-sw.png b/content/en/building/translations/localizing/messages-tab-language-sw.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/messages-tab-language-sw.png
rename to content/en/building/translations/localizing/messages-tab-language-sw.png
diff --git a/content/en/building/translations/configuring-translations/new-person-form-english.png b/content/en/building/translations/localizing/new-person-form-english.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/new-person-form-english.png
rename to content/en/building/translations/localizing/new-person-form-english.png
diff --git a/content/en/building/translations/configuring-translations/new-person-form-swahili.png b/content/en/building/translations/localizing/new-person-form-swahili.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/new-person-form-swahili.png
rename to content/en/building/translations/localizing/new-person-form-swahili.png
diff --git a/content/en/building/translations/configuring-translations/new-person-form.png b/content/en/building/translations/localizing/new-person-form.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/new-person-form.png
rename to content/en/building/translations/localizing/new-person-form.png
diff --git a/content/en/building/translations/configuring-translations/new-person-xls-form.png b/content/en/building/translations/localizing/new-person-xls-form.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/new-person-xls-form.png
rename to content/en/building/translations/localizing/new-person-xls-form.png
diff --git a/content/en/building/translations/configuring-translations/people-translation-en.png b/content/en/building/translations/localizing/people-translation-en.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/people-translation-en.png
rename to content/en/building/translations/localizing/people-translation-en.png
diff --git a/content/en/building/translations/configuring-translations/people-translation-sw.png b/content/en/building/translations/localizing/people-translation-sw.png
similarity index 100%
rename from content/en/building/translations/configuring-translations/people-translation-sw.png
rename to content/en/building/translations/localizing/people-translation-sw.png
diff --git a/content/en/building/translations/managing-translations.md b/content/en/building/translations/managing.md
similarity index 63%
rename from content/en/building/translations/managing-translations.md
rename to content/en/building/translations/managing.md
index c8b2f5672..2513acc09 100644
--- a/content/en/building/translations/managing-translations.md
+++ b/content/en/building/translations/managing.md
@@ -1,28 +1,37 @@
 ---
 title: Managing
 linkTitle: Managing
-weight: 2
+weight: 3
 description: >
-  Adding translations in CHT Core
+  Managing translations in the CHT
 relatedContent: >  
-  building/translations/localizing-translations
+  building/translations/localizing
 aliases:
    - /core/overview/translations
+   - /building/translations/managing-translations
 ---
 
-Apps built with CHT Core are localized so that users can use them in the language of their choice. Languages supported by default are English, French, Nepali, Spanish, and Swahili. The goal of this doc is to help the community manage these and future translations.
+Apps built with CHT Core are localized so that users can use them in the language of their choice. The goal of this section is to help the community manage existing and new translations.
+
+{{% alert title="Note" color="info" %}}
+Please open [an issue](https://github.com/medic/cht-core/issues/new) if you are interested in translating the CHT into a different language, and make it available to the community.
+{{% /alert %}}
 
 ## Overview
 
-Like the rest of the code the translation files live in the GitHub repo. These translation files are [properties files](https://en.wikipedia.org/wiki/.properties), which are a series of keys and their corresponding values. The English file is used by default, and as such, it contains the entire set of keys. If any key is missing from another language file the English value is used.
+Translation files live in the GitHub repo. These translation files are [properties files](https://en.wikipedia.org/wiki/.properties), which are a series of keys and their corresponding values. The English file is used by default, and as such, it contains the entire set of keys. If any key is missing from another language file the English value is used.
+
+New elements in CHT apps, such as tasks, targets, profiles, and forms should be localized as well. These labels should be included in the same custom translations properties file. If a translation is missing for the user's language it will use that of the default language. 
 
 ## Adding new languages
 
 New languages must be added and configured in several places:
 
-- Create a new `messages-xx.properties` file in the [`api/resources/translations`](https://github.com/medic/cht-core/tree/master/api/resources/translations) folder, replacing "xx" with the 2 or 3 letter [language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).
+- Create a new `messages-xx.properties` file in the [`api/resources/translations`](https://github.com/medic/cht-core/tree/master/api/resources/translations) folder, replacing "xx" with the 2 or 3 letter [language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). The language code will be used to identify the language in the application. For instance, for English, we would have a `translations/messages-en.properties` file. 
 - Add the language to the [`LOCAL_NAME_MAP` in api](https://github.com/medic/cht-core/blob/e6d184946affc62773d569168216a5b913f38a30/api/src/translations.js#L17). Use the language code for the key, and the local name followed by the English name for the language in brackets, eg: "fr: 'Français (French)'".
 - Import the moment language pack in the [main.ts file](https://github.com/medic/cht-core/blob/e6d184946affc62773d569168216a5b913f38a30/webapp/src/ts/main.ts#L23). If moment doesn't provide the required language pack you may need to contribute it upstream to the moment library.
+- Import the bootstrap-datepicker language pack in the [Enketo main.ts file](https://github.com/medic/cht-core/blob/master/webapp/src/js/enketo/main.js). If bootstrap-datepicker doesn't provide the required language pack you may need to create a custom language pack as in the [Luganda language example](https://github.com/medic/cht-core/blob/master/webapp/src/js/enketo/bootstrap-datepicker.lg.js).
+- Add a `TRANSLATIONS` entry for the new language in the [translator.js file](https://github.com/medic/cht-core/blob/master/webapp/src/js/bootstrapper/translator.js).
 
 ## Adding new keys
 
diff --git a/content/en/building/translations/overview.md b/content/en/building/translations/overview.md
new file mode 100644
index 000000000..f1dea28f0
--- /dev/null
+++ b/content/en/building/translations/overview.md
@@ -0,0 +1,49 @@
+---
+title: Overview
+linkTitle: Overview
+weight: 1
+description: >
+  Supporting localization and adding translations in the CHT
+aliases:
+   - /building/translations/translations-overview
+   - /building/reference/translations
+   - /apps/reference/translations
+---
+
+Given that CHT applications are used around the world, the Core Framework was designed with localization in mind. The Core Framework is available in English, French, Hindi, Nepali, Spanish, Swahili, Arabic, and Indonesian.
+
+## Key Concepts
+
+*Localization* refers to setting up the desired language in CHT for the end user. See an outline of how to change language settings for CHT users [in the dedicated section]({{< ref "building/translations/localizing" >}}).
+
+*Translations* refers to manually setting up extra translations of instance tabs texts or outgoing SMS text. See an outline of how to do add new translations to the CHT [in the dedicated section]({{< ref "building/translations/managing" >}}).
+
+## Localization
+In the `app_settings.json` file the default language for the application is set by the `locale` property, along with a separate default language for outgoing messages that are sent via SMS with the `locale_outgoing` property.  
+
+Additionally, languages available to the user can be enabled and disabled through the `languages` property which contains an array of objects. These objects should contain the `locale` and `enabled` properties representing respectively the 2 or 3 letter language code and whether that language should be enabled.
+
+### Forms
+Translations for XForms are defined within the forms themselves. The XLSForm notation is [documented here](http://xlsform.org/en/#multiple-language-support), and would use the corresponding 2-character language codes.
+
+### Reports
+
+Submitted forms are shown on the Reports tab, with each value in the report displayed alongside a label. The label for each value is represented by a key in the `report.{form-name}.{field-name}` format, which can be translated by including the key and translation in the [language files]( {{< relref "#translations" >}} ). If the label is omitted in the translation the full key will show in the app.
+
+{{% alert title="Note" color="info" %}}
+To hide report fields from showing on the Reports view altogether, the containing group or field must be included as `hidden_fields`, as per the [form properties file]( {{< ref "building/forms/app#properties" >}} ).
+{{% /alert %}}
+
+### Build 
+
+Custom translations from the properties files are added to the CHT app with the `upload-custom-translations` action.
+
+```shell
+cht --local upload-custom-translations
+```
+    
+Updated translations from forms need to be added with the actions to upload forms.
+
+```shell
+cht --local upload-contact-forms upload-app-forms
+```
\ No newline at end of file
diff --git a/content/en/building/translations/translations-overview.md b/content/en/building/translations/translations-overview.md
deleted file mode 100644
index cf1cf0ace..000000000
--- a/content/en/building/translations/translations-overview.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: Overview
-weight: 1
-description: >
- Building language translations in the CHT
----
-Given that CHT apps are used around the world, the Core Framework was designed with localization in mind. The Core Framework itself is available in English, French, Hindi, Nepali, Spanish, Swahili, and Indonesian.
-## Brief Overview of Key Concepts
-
-*Localization* this is  setting up the desired language in CHT for the end user.
-
-*Translations* this is manually setting up extra translations of instance tabs texts or outgoing SMS text. See an outline of how to do that [here]({{< ref "building/translations/localizing-translations#translations" >}}).
-
-## Required Resources
-
-You should have a functioning [CHT instance with `cht-conf` installed locally]({{< ref "building/local-setup" >}}), completed a [project folder]({{< ref "building/local-setup#3-create-and-upload-a-blank-project" >}}) setup, and an [messages-sw.properties]({{< ref "building/translations/localizing-translations" >}}) file.
\ No newline at end of file
diff --git a/content/en/building/tutorials/sms-forms.md b/content/en/building/tutorials/sms-forms.md
index 260ba3539..65e286d47 100644
--- a/content/en/building/tutorials/sms-forms.md
+++ b/content/en/building/tutorials/sms-forms.md
@@ -147,7 +147,7 @@ To set the validation rules and autoresponses, edit the array corresponding to t
 
 You can also define your own [validation rules]({{< ref "building/reference/app-settings#validations" >}}).
 
-{{% alert title="Note" %}} `translation_key` represents the message that is sent out. This will be defined in a [translations]({{< ref "building/translations/localizing-translations" >}}) file. {{% /alert %}}
+{{% alert title="Note" %}} `translation_key` represents the message that is sent out. This will be defined in a [translations]({{< ref "building/translations/managing" >}}) file. {{% /alert %}}
 
 ### 3. Define a Person Registration Form
 
diff --git a/content/en/contribute/code/_index.md b/content/en/contribute/code/_index.md
index 2e470a397..bedc0ea04 100644
--- a/content/en/contribute/code/_index.md
+++ b/content/en/contribute/code/_index.md
@@ -52,7 +52,7 @@ Want to talk about Documentation generally? Join our [Community Forum](https://f
 
 ### Translations
 
-If you are a translator but not a developer, we understand that you may need extra help to follow the [process of translating]({{% ref "building/translations/localizing-translations" %}}) software for the first time. If that is the case, please open an issue on the GitHub repo or start a topic on the community forum.
+If you are a translator but not a developer, we understand that you may need extra help to follow the [process of translating]({{% ref "building/translations/managing" %}}) software for the first time. If that is the case, please open an issue on the GitHub repo or start a topic on the community forum.
 
 ### Disclosing vulnerabilities
 
diff --git a/content/en/why-the-cht.md b/content/en/why-the-cht.md
index f6ed93d54..80aaafac2 100644
--- a/content/en/why-the-cht.md
+++ b/content/en/why-the-cht.md
@@ -79,9 +79,9 @@ Around the world, countries are adopting a model of primary health care that sta
 
 <img src="localization.png" width="23%" align="right" />
 
-Apps can be customized for different deployments and types of workflows. The Core Framework has been used in dozens of countries around the world with [localization settings]({{< ref "building/translations/localizing-translations" >}}).
+Apps can be customized for different deployments and types of workflows. The Core Framework has been used in dozens of countries around the world with [localization settings]({{< ref "building/translations/localizing" >}}).
 
-Users can currently interact with the app in English, French, Hindi, Nepali, Spanish, Swahili, or Indonesian and new languages can be added in the admin console. The app also supports Bikram Sambat or Gregorian calendars and localized date formatting.
+Users can currently interact with the app in English, French, Hindi, Nepali, Spanish, Swahili, Arabic, or Indonesian and new languages can be added in the admin console. The app also supports Bikram Sambat or Gregorian calendars and localized date formatting.
 
 ## Example and reference apps