From c5753b27e361dab964be244d02db887ba1366156 Mon Sep 17 00:00:00 2001
From: Bruno Alla <alla.brunoo@gmail.com>
Date: Wed, 31 May 2023 20:41:58 +0100
Subject: [PATCH] Convert locale readme to markdown and expand a bit the
 instructions

---
 .../locale/README.md                          | 32 +++++++++++++++++++
 .../locale/README.rst                         | 19 -----------
 2 files changed, 32 insertions(+), 19 deletions(-)
 create mode 100644 {{cookiecutter.project_slug}}/locale/README.md
 delete mode 100644 {{cookiecutter.project_slug}}/locale/README.rst

diff --git a/{{cookiecutter.project_slug}}/locale/README.md b/{{cookiecutter.project_slug}}/locale/README.md
new file mode 100644
index 000000000..8377ee457
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/locale/README.md
@@ -0,0 +1,32 @@
+# Translations
+
+Translations strings will be placed in this folder when running:
+
+```bash
+{% if cookiecutter.use_docker == 'y' %}docker-compose -f local.yml run --rm django {% endif %}python manage.py makemessages -all --no-location
+```
+
+This should generate `django.po` (stands for Portable Object) files under each locale `<locale name>/LC_MESSAGES/django.po`. Each translatable string in the codebase is collected with its `msgid` and need to be translated as `msgstr`, for example:
+
+```po
+msgid "users"
+msgstr "utilisateurs"
+```
+
+Once all translations are done, they need to be compiled into `.mo` files (stands for Machine Object), which are the actual binary files used by the application:
+
+```bash
+{% if cookiecutter.use_docker == 'y' %}docker-compose -f local.yml run --rm django {% endif %}python manage.py compilemessages
+```
+
+Note that the `.po` files are NOT used by the application directly, so if the `.mo` files are out of dates, the content won't appear as translated even if the `.po` files are up-to-date.
+
+## Production
+
+The production image runs `compilemessages` automatically at build time, so as long as your translated source files (PO) are up-to-date, you're good to go.
+
+## Add a new language
+
+1. Update/add the [`LANGUAGES` setting](https://docs.djangoproject.com/en/stable/ref/settings/#std-setting-LANGUAGES) to your project's base settings.
+2. Create the locale folder for the language next to this file, e.g. `fr_FR` for French. Make sure the case is correct.
+3. Run `makemessages` (as instructed above) to generate the PO files for the new language.
diff --git a/{{cookiecutter.project_slug}}/locale/README.rst b/{{cookiecutter.project_slug}}/locale/README.rst
deleted file mode 100644
index b46feb1c2..000000000
--- a/{{cookiecutter.project_slug}}/locale/README.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-Translations
-============
-
-Translations strings will be placed in this folder when running::
-
-    {% if cookiecutter.use_docker == 'y' %}docker-compose -f local.yml run --rm django {% endif %}python manage.py makemessages -all --no-location
-
-This should generate ``django.po`` (stands for Portable Object) files under each locale `<locale name>/LC_MESSAGES/django.po`. Each translatable string in the codebase is collected with its ``msgid`` and need to be translated as ``msgstr``, for example::
-
-    msgid "users"
-    msgstr "utilisateurs"
-
-Once all translations are done, they need to be compiled into ``.mo`` files (stands for Machine Object), which are the actual binary files used by the application::
-
-    {% if cookiecutter.use_docker == 'y' %}docker-compose -f local.yml run --rm django {% endif %}python manage.py compilemessages
-
-Note that the ``.po`` files are NOT used by the application directly, so if the ``.mo`` files are out of dates, the content won't appear as translated even if the ``.po`` files are up to date.
-
-The production image runs ``compilemessages`` automatically at build time, so as long as your translated source files (PO) are up to date, you're good to go.