✨(frontend) adds customization for translations

Part of customization PoC

Author: rvveber

src/frontend/apps/impress/src/core/config/ConfigProvider.tsx

@@ -4,7 +4,10 @@ import { PropsWithChildren, useEffect } from 'react';
 
 import { Box } from '@/components';
 import { useCunninghamTheme } from '@/cunningham';
-import { useLanguageSynchronizer } from '@/features/language/';
+import {
+  useLanguageSynchronizer,
+  useTranslationsCustomizer,
+} from '@/features/language/';
 import { useAnalytics } from '@/libs';
 import { CrispProvider, PostHogAnalytic } from '@/services';
 import { useSentryStore } from '@/stores/useSentryStore';
@@ -17,6 +20,7 @@ export const ConfigProvider = ({ children }: PropsWithChildren) => {
   const { setTheme } = useCunninghamTheme();
   const { AnalyticsProvider } = useAnalytics();
   const { synchronizeLanguage } = useLanguageSynchronizer();
+  const { customizeTranslations } = useTranslationsCustomizer();
 
   useEffect(() => {
     if (!conf?.SENTRY_DSN) {
@@ -35,8 +39,10 @@ export const ConfigProvider = ({ children }: PropsWithChildren) => {
   }, [conf?.FRONTEND_THEME, setTheme]);
 
   useEffect(() => {
-    void synchronizeLanguage();
-  }, [synchronizeLanguage]);
+    void synchronizeLanguage().finally(() => {
+      void customizeTranslations();
+    });
+  }, [synchronizeLanguage, customizeTranslations]);
 
   useEffect(() => {
     if (!conf?.POSTHOG_KEY) {

src/frontend/apps/impress/src/core/config/api/useConfig.tsx

@@ -12,6 +12,7 @@ interface ConfigResponse {
   CRISP_WEBSITE_ID?: string;
   FRONTEND_THEME?: Theme;
   FRONTEND_CSS_URL?: string;
+  FRONTEND_CUSTOM_TRANSLATIONS_URL?: string;
   MEDIA_BASE_URL?: string;
   POSTHOG_KEY?: PostHogConf;
   SENTRY_DSN?: string;

src/frontend/apps/impress/src/features/language/hooks/useTranslationsCustomizer.ts

@@ -0,0 +1,138 @@
+import i18next, { Resource } from 'i18next';
+import { useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useConfig } from '@/core';
+
+const CACHE_KEY = 'docs_custom_translations';
+const CACHE_URL_KEY = 'docs_custom_translations_url';
+
+const safeLocalStorage = {
+  getItem: (key: string): string | null => {
+    if (typeof window === 'undefined') {
+      return null;
+    }
+    return localStorage.getItem(key);
+  },
+  setItem: (key: string, value: string): void => {
+    if (typeof window === 'undefined') {
+      return;
+    }
+    localStorage.setItem(key, value);
+  },
+};
+
+export const useTranslationsCustomizer = () => {
+  const { data: conf } = useConfig();
+  const [isCustomized, setIsCustomized] = useState<boolean | null>(null);
+  const { i18n } = useTranslation();
+
+  // Apply custom translations to i18next
+  const applyCustomTranslations = useCallback(
+    (translations: Resource) => {
+      if (!translations) {
+        setIsCustomized(false);
+        return;
+      }
+
+      // Add each language's custom translations with proper namespace handling
+      Object.entries(translations).forEach(([lng, namespaces]) => {
+        Object.entries(namespaces).forEach(([ns, value]) => {
+          i18next.addResourceBundle(lng, ns, value, true, true);
+        });
+      });
+
+      const currentLanguage = i18n.language;
+      void i18next.changeLanguage(currentLanguage);
+
+      // Emit added event to make sure components re-render
+      i18next.emit('added', currentLanguage, 'translation');
+
+      setIsCustomized(true);
+    },
+    [i18n],
+  );
+
+  const fetchAndApplyCustomTranslations = useCallback(
+    async (url: string) => {
+      try {
+        const response = await fetch(url);
+        if (!response.ok) {
+          throw new Error('Failed to fetch custom translations');
+        }
+
+        const translations = (await response.json()) as Resource;
+
+        // Cache for future use
+        safeLocalStorage.setItem(CACHE_KEY, JSON.stringify(translations));
+        safeLocalStorage.setItem(CACHE_URL_KEY, url);
+
+        // Apply the translations
+        applyCustomTranslations(translations);
+
+        return true;
+      } catch (e) {
+        console.error('Error fetching custom translations:', e);
+        safeLocalStorage.setItem(CACHE_KEY, 'false');
+        safeLocalStorage.setItem(CACHE_URL_KEY, url || '');
+        setIsCustomized(false);
+
+        return false;
+      }
+    },
+    [applyCustomTranslations],
+  );
+
+  // Main function to customize translations
+  const customizeTranslations = useCallback(async () => {
+    // Skip if already processed or no config
+    if (isCustomized !== null || !conf) {
+      return;
+    }
+
+    const customUrl = conf.FRONTEND_CUSTOM_TRANSLATIONS_URL;
+    const cachedUrl = safeLocalStorage.getItem(CACHE_URL_KEY);
+
+    // Fast path: If we have cached translations for the same URL
+    if (cachedUrl === customUrl) {
+      const cached = safeLocalStorage.getItem(CACHE_KEY);
+
+      if (cached) {
+        try {
+          // Apply cached translations immediately
+          if (cached !== 'false') {
+            const parsedTranslations = JSON.parse(cached) as Resource;
+            applyCustomTranslations(parsedTranslations);
+          } else {
+            setIsCustomized(false);
+          }
+
+          // Update cache in background if URL is provided
+          if (customUrl) {
+            void fetchAndApplyCustomTranslations(customUrl);
+          }
+
+          return;
+        } catch (e) {
+          console.error('Error parsing cached translations:', e);
+        }
+      }
+    }
+
+    // No valid cache, fetch new translations or mark as not customized
+    if (customUrl) {
+      await fetchAndApplyCustomTranslations(customUrl);
+    } else {
+      safeLocalStorage.setItem(CACHE_KEY, 'false');
+      safeLocalStorage.setItem(CACHE_URL_KEY, '');
+      setIsCustomized(false);
+    }
+  }, [
+    conf,
+    isCustomized,
+    applyCustomTranslations,
+    fetchAndApplyCustomTranslations,
+  ]);
+
+  return { customizeTranslations, isCustomized };
+};

src/frontend/apps/impress/src/features/language/index.ts

@@ -1,2 +1,3 @@
 export * from './hooks/useLanguageSynchronizer';
+export * from './hooks/useTranslationsCustomizer';
 export * from './LanguagePicker';

src/frontend/apps/impress/src/i18n/initI18n.ts

@@ -7,33 +7,39 @@ import resources from './translations.json';
 export const availableFrontendLanguages: readonly string[] =
   Object.keys(resources);
 
-i18next
-  .use(LanguageDetector)
-  .use(initReactI18next)
-  .init({
-    resources,
-    fallbackLng: 'en',
-    debug: false,
-    detection: {
-      order: ['cookie', 'navigator'], // detection order
-      caches: ['cookie'], // Use cookies to store the language preference
-      lookupCookie: 'docs_language',
-      cookieMinutes: 525600, // Expires after one year
-      cookieOptions: {
-        path: '/',
-        sameSite: 'lax',
+// Add an initialization guard
+let isInitialized = false;
+
+// Initialize i18next with the base translations only once
+if (!isInitialized && !i18next.isInitialized) {
+  isInitialized = true;
+
+  i18next
+    .use(LanguageDetector)
+    .use(initReactI18next)
+    .init({
+      resources,
+      fallbackLng: 'en',
+      debug: false,
+      detection: {
+        order: ['cookie', 'navigator'],
+        caches: ['cookie'],
+        lookupCookie: 'docs_language',
+        cookieMinutes: 525600,
+        cookieOptions: {
+          path: '/',
+          sameSite: 'lax',
+        },
+      },
+      interpolation: {
+        escapeValue: false,
       },
-    },
-    interpolation: {
-      escapeValue: false,
-    },
-    preload: availableFrontendLanguages,
-    lowerCaseLng: true,
-    nsSeparator: false,
-    keySeparator: false,
-  })
-  .catch(() => {
-    throw new Error('i18n initialization failed');
-  });
+      preload: availableFrontendLanguages,
+      lowerCaseLng: true,
+      nsSeparator: false,
+      keySeparator: false,
+    })
+    .catch((e) => console.error('i18n initialization failed:', e));
+}
 
 export default i18next;