From b08e459cbe7562b60cc6d9c465d72ecc88f18f3f Mon Sep 17 00:00:00 2001
From: Ewen Le Bihan <hey@ewen.works>
Date: Sun, 14 Apr 2024 23:59:45 +0200
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Internationalization=20page?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .vitepress/config.mts      |  4 +++
 db/internationalization.md | 53 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/.vitepress/config.mts b/.vitepress/config.mts
index 9fe222c..ca92b38 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -31,6 +31,10 @@ const ortfodbSidebar = [
         text: "Markdown",
         link: "db/markdown",
       },
+			{
+				text: "Internationalization",
+				link: "db/internationalization",
+			},
       {
         text: "Thumbnail generation",
         link: "db/thumbnails",
diff --git a/db/internationalization.md b/db/internationalization.md
index e69de29..86c293a 100644
--- a/db/internationalization.md
+++ b/db/internationalization.md
@@ -0,0 +1,53 @@
+# Internationalization
+
+To share your works with the world, and with your future job, you might want to translate your works' descriptions to multiple languages. ortfo/db has _first-class_ support for this by allowing you to define your works' descriptions in multiple languages.
+
+## Language markers
+
+Simply add a _language marker_ in your description file on its own line. Everything that you write after this marker, and before the next marker, is considered to be written in that language.
+
+The markers look like this:
+
+```md
+:: language code
+```
+
+Note that this “language code” could technically be anything you want, but it's recommended (and might in the future be required to be) a [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) language code.
+
+### Example
+
+```md
+---
+wip: yes
+---
+
+# ortfo
+
+:: en
+
+A simple way to manage _lots_ of projects for a portfolio website
+
+:: fr
+
+Une manière simple de gérer _beaucoup_ de projets pour un site web de portfolio
+
+:: ja
+
+私の日本語は悪いですから、知らないwwww
+```
+
+## Untranslated content
+
+Content that isn't translated is considered to have the special language code `default`.
+
+All content before any language markers is considered untranslated.
+
+This is particularly useful for the title of the work, which is usually the same in all languages.
+
+## In `database.json`
+
+The database's [Content](/db/database-format.md#content) will be an object mapping every language code used in the description file to the content blocks of the work.
+
+## `layout` considerations
+
+Since the [Layout](/db/layouts.md) is shared by all languages, you must have the same number of paragraph, links and media blocks in every language.