chore(condo): language customization (#5911)

* chore(condo): draft: language customization

* chore(condo): draft: language customization

* chore(condo): draft: add translations linter

* chore(condo): remove test translation

* chore(condo): add guide

Author: toplenboren

apps/condo/README.md

@@ -5,4 +5,30 @@ Condo development guide
 * [Project structure](./docs/project-structure.md)
 * [Migrations guide](./docs/migrations.md)
 * [Utils](./docs/utils)
-* [Checklists](./docs/checklists)
+* [Checklists](./docs/checklists)
+
+## Customization guide for open source developers
+
+### Adding translations
+
+Sometimes, in your custom forks you need to add or override translations, for this you should write custom translations in `lang/<locale>/<locale>.custom.json`
+
+These translations then can be used just as regular translations in condo
+
+`lang/en/en.custom.json`
+```json
+{
+  "custom.example": "Test"
+}
+```
+
+`any component`
+```js
+const TestCustomTranslation = intl.formatMessage({ id: 'custom.example' })
+
+console.log(TestCustomTranslation) // Test
+```
+
+Translations inside the custom translations file **will overwrite** other translations.
+
+Best practice is to start your custom translation with prefix `custom`, that way it is guaranteed that these translations will not collide with translations in condo

apps/condo/domains/common/utils/clientSchema/messagesImporter.ts

@@ -1,4 +1,10 @@
 export async function messagesImporter (locale: string) {
-    const locale_data = await import(`@app/condo/lang/${locale}/${locale}`)
-    return locale_data.default
+    const localeData = await import(`@app/condo/lang/${locale}/${locale}`)
+
+    const customLocaleData = await import(`@app/condo/lang/${locale}/${locale}.custom`)
+    if (customLocaleData) {
+        return { ...localeData.default, ...customLocaleData.default }
+    }
+
+    return localeData.default
 }

apps/condo/global.d.ts

@@ -1,11 +1,19 @@
 import { GetActiveOrganizationEmployeeQuery, AuthenticatedUserQuery } from '@app/condo/gql'
+import enCustom from '@app/condo/lang/en/en.custom.json'
 import en from '@app/condo/lang/en/en.json'
+import es from '@app/condo/lang/es/es.json'
+import esCustom from '@app/condo/lang/ru/es.custom.json'
+import ruCustom from '@app/condo/lang/ru/ru.custom.json'
 import ru from '@app/condo/lang/ru/ru.json'
 
 
 // NOTE: Combine all keys together
-const translations = [en, ru] as const
-type MessagesKeysType = keyof typeof translations[number]
+const translations = [en, ru, es] as const
+const customTranslations = [enCustom, ruCustom, esCustom] as const
+
+type TranslationsKeysType = keyof typeof translations[number]
+type CustomTranslationsKeysType = keyof typeof customTranslations[number]
+type MessagesKeysType = TranslationsKeys | CustomTranslationsKeys
 
 type LinkExtendsType = GetActiveOrganizationEmployeeQuery['employees'][number]
 type OrganizationExtendsType = GetActiveOrganizationEmployeeQuery['employees'][number]['organization']

apps/condo/lang/en/en.custom.json

@@ -0,0 +1,3 @@
+{
+  "custom.example": "Test"
+}

apps/condo/lang/es/es.custom.json

@@ -0,0 +1,3 @@
+{
+  "custom.example": "ES Test"
+}

apps/condo/lang/ru/ru.custom.json

@@ -0,0 +1,3 @@
+{
+  "custom.example": "Тест"
+}

bin/lint-i18n-translations.js

@@ -5,6 +5,8 @@ const util = require('util')
 
 const execPromise = util.promisify(exec)
 
+const RESERVED_PREFIXES = ['custom']
+
 async function writeTranslationData (translationFilePath, translationData) {
     const sortedTranslationData = Object.keys(translationData).sort().reduce((acc, key) => {
         acc[key] = translationData[key]
@@ -55,7 +57,23 @@ async function saveTranslations (langDir, translations) {
     }
 }
 
-async function validateTranslations (translations) {
+async function getKeysWithReservedPrefixes (translations) {
+    const keysWithReservedPrefixes = []
+
+    translations.forEach(([, keys]) => {
+        keys.forEach(key => {
+            RESERVED_PREFIXES.forEach(reservedPrefix => {
+                if (key.startsWith(reservedPrefix)) {
+                    keysWithReservedPrefixes.push(key)
+                }
+            })
+        })
+    })
+
+    return keysWithReservedPrefixes
+}
+
+async function getMissingKeys (translations) {
     const allKeys = new Set()
     translations.forEach(([, keys]) => {
         keys.forEach(key => allKeys.add(key))
@@ -143,7 +161,7 @@ async function main () {
     const langDir = path.join(root, 'lang')
 
     const translations = await loadTranslations(langDir)
-    const missingKeysReport = await validateTranslations(translations)
+    const missingKeysReport = await getMissingKeys(translations)
 
     if (missingKeysReport.length > 0) {
         if (shouldFix) {
@@ -153,6 +171,11 @@ async function main () {
         }
     }
 
+    const keysWithReservedPrefixes = await getKeysWithReservedPrefixes(translations)
+    if (keysWithReservedPrefixes.length > 0) {
+        throw new Error(`Keys starting with one of reserved prefixes: [${RESERVED_PREFIXES.join(', ')}] found. Please check your translation files and fix those keys`)
+    }
+
     if (shouldFix) {
         await saveTranslations(langDir, translations)
     }