From 4ca517cc218948bcda716898a4da63c0582143fc Mon Sep 17 00:00:00 2001
From: Mathieu Lu <mathieu@bidon.ca>
Date: Mon, 6 Nov 2017 22:46:37 -0500
Subject: [PATCH] database.md: localized fields

---
 docs/translation/database.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/translation/database.md b/docs/translation/database.md
index 9f00b420..67e3f1e5 100644
--- a/docs/translation/database.md
+++ b/docs/translation/database.md
@@ -1,4 +1,4 @@
-# Database upgrades
+# Database localized fields and upgrades
 
 ## PHP code related to database upgrades
 
@@ -18,6 +18,31 @@ For example, do not translate:
 $this->addTask('Update financial_account_id in financial_trxn table', 'updateFinancialTrxnData', $rev);
 ```
 
+## Localized fields
+
+Any value stored in the database that may depend on the language must be localizable. For example:
+
+* A contribution page title or description,
+* A group title or description,
+* A configurable string to display on forms (ex: a custom "submit" button label).
+
+However, since localizable fields add a certain technical complexity, the following type of fields are not localized:
+
+* Contact information, such as the first name, nickname, etc.
+* Address fields.
+
+While there are many cities where street names can officially be in multiple languages (or have official transliterations), users usually enter their address only in one language. It is rarely required to store the address translation (one exception: event locations, which is currently a known limitation).
+
+Similarly, the first and last name of an individual may be written in different alphabets (ex: Latin and Cyrillic), but this is not a frequent use-case worth the complexity. Adminstrators can workaround this by creating custom fields.
+
+In order to define a field as localizable, the XML schema files must have the following tag:
+
+```
+<localizable>true</localizable>
+```
+
+If a new field was not initially tagged as localizable, the upgrade must explicitely convert the field. See the section below on localised fields schema changes.
+
 ## SQL upgrades
 
 SQL upgrades must account for two use-cases:
-- 
GitLab