From 38410049da244e53212742fb45cf7771a862e1c9 Mon Sep 17 00:00:00 2001
From: Hsiaoming Yang <me@lepture.com>
Date: Fri, 30 Aug 2024 23:50:47 +0900
Subject: [PATCH] docs: update translation guide

---
 Makefile                           |  2 +-
 docs/contributing/index.rst        |  3 ++
 docs/contributing/translations.rst | 46 ++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 docs/contributing/translations.rst

diff --git a/Makefile b/Makefile
index 40236d5..347a007 100644
--- a/Makefile
+++ b/Makefile
@@ -16,7 +16,7 @@ babel-init:
 	pybabel init -D sphinx -i src/shibuya/locale/sphinx.pot -d src/shibuya/locale -l ${lang}
 
 babel-update:
-	pybabel update -D sphinx -i src/shibuya/locale/sphinx.pot -d src/shibuya/locale
+	pybabel update -D sphinx -i src/shibuya/locale/sphinx.pot -d src/shibuya/locale -l ${lang}
 
 babel-compile:
 	pybabel compile -D sphinx -d src/shibuya/locale
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
index a70c4f4..dc3e762 100644
--- a/docs/contributing/index.rst
+++ b/docs/contributing/index.rst
@@ -35,6 +35,8 @@ Everyone wants a good documentation. There may be mistakes
 or things missing in the documentation, you're welcome to
 help us improving the documentation.
 
+.. _development:
+
 Development
 -----------
 
@@ -101,4 +103,5 @@ Now, your environment is ready for development. Open your browser, and visit
 .. toctree::
    :hidden:
 
+   translations
    roadmap
diff --git a/docs/contributing/translations.rst b/docs/contributing/translations.rst
new file mode 100644
index 0000000..28fa541
--- /dev/null
+++ b/docs/contributing/translations.rst
@@ -0,0 +1,46 @@
+:description: Help us translating this documentation into other languages.
+
+Translations
+============
+
+To begin translating this documentation into other languages, please
+start by referring to the :ref:`development` guide, which will help
+you set up a suitable development environment.
+
+Adding a new language
+---------------------
+
+First, we need to generate the ``.po`` file in your preferred language:
+
+.. code-block:: shell
+
+    make babel-init lang=it
+
+In this example, we're using the language code ``it`` to represent Italian.
+
+Updating languages
+------------------
+
+If the language exists, you can update the ``.po`` files using the
+following command:
+
+.. code-block:: shell
+
+    make babel-update lang=it
+
+Writing the translations
+------------------------
+
+Following the previous command, the ``.po`` files will be generated within
+the ``src/shibuya/locale/it/LC_MESSAGES`` directory. You can now edit these
+files to add the Italian translations accordingly.
+
+Compiling the translations
+--------------------------
+
+Once, the translations are completed. You need to compile the translations
+before validating it.
+
+.. code-block:: shell
+
+    make babel-compile