Feature/custom translations frontend

[rvveber]

Adds ability to inject/override translations at runtime.
Moves contents of docs/theming.md into docs/customization.md for a more unified documentation.

[AntoLC]

Could it be done in the useLanguageSynchronizer hook, after synchronizeLanguage ?

[rvveber]

It would tightly couple useLanguageSynchronizer with useTranslationsCustomizer hook.
What benefit would it bring?

[rvveber]

I improved it. No more async or void calls and no dependency chains.
Check it out.
✅

[AntoLC]

I think "Runtime Theming" is better, we want that users understand that it is a way to overwrite the theme of the App.

Suggested change

	## Custom CSS
	## Runtime Theming 🎨

[rvveber]

Hm, but currently it is just custom CSS right?

• For Theming it would need to include an example of overwriting a css variable that is generated by the theme.
• All customizations are/should be and usually are expected to be at runtime, from a customizers point of view atleast, so explicitly adding runtime, suggest that translations are not customized at runtime. It is confusing
• Target user group for documentation is one that knows what css is, it's the requirement to theme, i don't think we need to name it something else to explain what is possible to non-technicals. For that maybe the README would be a better place.
• We want to avoid build-time customizations entirely, and for now all content of this documentation is at run-time, why make it extra?

[AntoLC]

We want to offer 2 different ways, to override the theme, 1 runtime, 1 buildtime, so it makes sense to say that this one is the runtime way. It depends the case, runtime does not every time fit the infrastructure you are working with, in our case we need the build time way for the moment concerning the theme.

[rvveber]

✅

[AntoLC]

I guess "custom-translation" will be less used than adding your theme at runtime, should be in second position I think.

Suggested change

	1. [Translations](#custom-translations)
	2. [CSS/Theme](#custom-css)
	1. [Runtime Theming](#runtime-theming)
	2. [Translations](#custom-translations)

[rvveber]

✅

[AntoLC]

Quite usefull, could maybe be available for the all Impress app. What about adding this code in /src/utils/storages.ts ?

[rvveber]

✅

[AntoLC]

Suggested change

	export const useTranslationsCustomizer = () => {
	const { data: conf } = useConfig();
	export const useTranslationsCustomizer = (translationsUrl:string) => {

[rvveber]

I decouple all required vars as parameters, for both TranslationCustomizer and LanguageSynchronizer
✅

[AntoLC]

Suggested change

	{
	"en": {
	"Docs": "Notes",
	"Create New Document": "+"
	},
	"de": {
	"Docs": "Notizen",
	"Create New Document": "+"
	}
	}
	{
	"en": {
	"translation": {
	"Docs": "Notes",
	"Create New Document": "+"
	}
	},
	"de": {
	"translation": {
	"Docs": "Notizen",
	"Create New Document": "+"
	}
	}
	}

[rvveber]

✅

[AntoLC]

I suppose you added this cache system to reduce the flickering, right ?

I don't think you should add this cache system, I think this hook should return a variable isTranslationLoading, and here (https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/core/config/ConfigProvider.tsx#L49-L54), you can just add:

  if (!conf || isTranslationLoading) {
    return (
      <Box $height="100vh" $width="100vw" $align="center" $justify="center">
        <Loader />
      </Box>
    );
  }

If conf.FRONTEND_CUSTOM_TRANSLATIONS_URL is not set, you can switch directly isTranslationLoading to false.

If really a "persistant" cache system has a strong purpose, we should leverage react-query, but I have the feeling it is ok for the moment.

WDYT ?

[rvveber]

I cached it, because we are waiting on two async requests here

1. fetch conf to receive the FRONTEND_CUSTOM_TRANSLATIONS_URL
2. fetch FRONTEND_CUSTOM_TRANSLATIONS_URL to receive the json

I think it is irresponsible to not cache it, since it would define a new critical-path/bottleneck for render-blocking loading times.

[rvveber]

But i'm also seeing now that i should not need to wait for conf.

1. If we have translations in cache, we should already apply them.
2. If the parallelly fetched translations are different we should apply them again.

[AntoLC]

I think that is a good point (critical-path/bottleneck for render-blocking loading times). I want to apply it to the config endpoint.

What about this pattern, more react-querish ?

import { useQuery } from '@tanstack/react-query';
import { Resource } from 'i18next';

import { APIError, errorCauses } from '@/api';

const LOCAL_STORAGE_KEY = 'CUSTOM_TRANSLATIONS';

function getCachedTranslation() {
  try {
    const jsonString = localStorage.getItem(LOCAL_STORAGE_KEY);
    return jsonString ? (JSON.parse(jsonString) as Resource) : undefined;
  } catch {
    return undefined;
  }
}

function setCachedTranslation(translations: Resource) {
  localStorage.setItem(LOCAL_STORAGE_KEY, JSON.stringify(translations));
}

export interface FetchCustomTranslationeParams {
  url?: string;
}

export const fetchCustomTranslation = async ({
  url,
}: FetchCustomTranslationeParams) => {
  if (!url) {
    return null;
  }

  const response = await fetch(url);
  if (!response.ok) {
    throw new APIError(
      'Failed to get the translation',
      await errorCauses(response),
    );
  }

  return response.json() as Promise<Resource>;
};

export const KEY_TRANSLATION = 'custom-translation';

export function useCustomTranslation(url?: string) {
  const cachedData = getCachedTranslation();
  const response = useQuery<Resource | null, APIError>({
    queryKey: [KEY_TRANSLATION, url || ''],
    queryFn: () => fetchCustomTranslation({ url }),
    initialData: cachedData,
    staleTime: 0,
    refetchOnWindowFocus: false,
    refetchOnReconnect: false,
  });

  if (response.data && response.isSuccess) {
    setCachedTranslation(response.data);
  }

  return response;
}

Then to call it, it would be quite easy:

export const useTranslationsCustomizer = (translationUrl?: string) => {
  const { i18n } = useTranslation();
  const { data: translations } = useCustomTranslation(translationUrl);

  useEffect(() => {
    if (!translations) {
      return;
    }

    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');
  }, [i18n.language, translations]);
};

[AntoLC]

I made this PR about the config cache optimization: #867
It is more optimized than the example provided.

[rvveber]

Optimized the code to be more compact, it didn't need nested queries or anything.
✅