I18n Translations API for Yoopta

[Darginec05]

I18n API for Yoopta

Hello everybody!
This discussion concerns frequently requested feature, the internationalization (i18n) for the editor.
At the moment, active work is underway in this PR (it is already at the final stage).
I would like to hear feedback from you and the community on the API for using i18n in Yoopta-Editor

@yoopta/i18n - new package for i18n

It has the export of the following useful modules:

import { withTranslation, useTranslation, type I18nYooEditor } from '@yoopta/i18n'

• withTranslation - required method for extending the editor's work with i18n
• useTranslation - hook for using language switching methods and translating texts by keys
• I18nYooEditor - extended type for YooEditor

Usage

See full example code - here

import { withTranslations } from '@yoopta/i18n';

import esTranslations from '@/locales/es.json';
import ruTranslations from '@/locales/ru.json';
import czTranslations from '@/locales/cz.json';

const TRANSLATIONS = {
  es: esTranslations,
  ru: ruTranslations,
  cz: czTranslations,
};

const ExampleWithTranslations = () => {
  const editor: YooEditor = useMemo(() => {
    const baseEditor = createYooptaEditor();
    return withTranslations(baseEditor, {
      translations: TRANSLATIONS,
      defaultLanguage: 'en',
      language: 'ru',
    });
  }, []);

  return (
    <YooptaEditor
      editor={editor}
      plugins={YOOPTA_PLUGINS}
      selectionBoxRoot={selectionRef}
      marks={MARKS}
      tools={TOOLS}
      style={EDITOR_STYLE}
      value={value}
      onChange={onChange}
      onPathChange={onPathChange}
      autoFocus={true}
      readOnly={false}
    />
  );
};

Example of translation data (example for @/locales/es.json)

{
  "editor": {
    "blockOptions": {
      "delete": "Borrar",
      "duplicate": "Duplicar",
      "turnInto": "Convertir en",
      "copyBlockLink": "Copiar enlace al bloque"
    },
    "placeholder": "Escribe '/' para comandos"
  },
  "plugins": {
    "Paragraph": {
      "display": {
        "title": "Párrafo",
        "description": "Párrafo de texto"
      }
    },
    "Blockquote": {
      "display": {
        "title": "Cita",
        "description": "Bloque de cita"
      }
    },
    "Callout": {
      "display": {
        "title": "Llamada",
        "description": "Bloque de llamada"
      }
    },
    "Accordion": {
      "display": {
        "title": "Acordeón",
        "description": "Bloque de acordeón"
      }
    },
    "BulletedList": {
      "display": {
        "title": "Lista con viñetas",
        "description": "Lista con viñetas"
      }
    },
    "NumberedList": {
      "display": {
        "title": "Lista numerada",
        "description": "Lista numerada"
      }
    },
    "TodoList": {
      "display": {
        "title": "Lista de tareas",
        "description": "Lista de tareas"
      }
    },
    "Image": {
      "display": {
        "title": "Imagen",
        "description": "Imagen"
      }
    },
    "Video": {
      "display": {
        "title": "Vídeo",
        "description": "Vídeo"
      }
    },
    "File": {
      "display": {
        "title": "Archivo",
        "description": "Archivo para descargar"
      }
    },
    "Table": {
      "display": {
        "title": "Tabla",
        "description": "Tabla"
      }
    },
    "Code": {
      "display": {
        "title": "Código",
        "description": "Bloque de código"
      }
    },
    "Divider": {
      "display": {
        "title": "Separador",
        "description": "Separador"
      }
    },
    "HeadingOne": {
      "display": {
        "title": "Título 1",
        "description": "Título de primer nivel"
      }
    },
    "HeadingTwo": {
      "display": {
        "title": "Título 2",
        "description": "Título de segundo nivel"
      }
    },
    "HeadingThree": {
      "display": {
        "title": "Título 3",
        "description": "Título de tercer nivel"
      }
    }
  },
  "tools": {
    "toolbar": {
      "highlightColor": {
        "text": "Texto",
        "background": "Fondo",
        "customColor": "Color personalizado"
      },
      "linkTitle": "Enlace"
    },
    "link": {
      "target": "Objetivo del enlace",
      "rel": "Relación del enlace",
      "update": "Actualizar",
      "add": "Añadir",
      "delete": "Eliminar enlace",
      "url": "URL",
      "title": "Título",
      "additionalProps": "Propiedades adicionales",
      "titlePlaceholder": "Editar título del enlace",
      "urlPlaceholder": "Editar URL del enlace",
      "targetPlaceholder": "Editar objetivo del enlace",
      "relPlaceholder": "Editar relación del enlace"
    }
  }
}

I18n API

With the withTranslation extension for the editor, Yoopta will have the following additional methods and keys:

export type I18nYooEditor<YKeys extends string = string> = YooEditor & {
  // your object of translations
  translations: Record<YKeys, Record<string, string>>;
  // current language
  language: string;
  // all available languages
  languages: string[];
  // default language
  defaultLanguage: string;
  // method to change language
  setLanguage: (lang: string) => void;
}

[gloaysa]

From what I've seen:

• TranslationManager is not used anymore, I guess we could remove it along with the whole i18n folder inside core/editor/src. (small detail, the TextLeaf component is using the useTranslation hook from this as an example, we need to remove it and use the new approach with `editor.getLabelText).
• The return value of the new useTranslation hook in the i18n package needs to be extended with setLanguage and currentLanguage.
• We need to somehow let the editor know when the language changes (I see we have an emit functionality built in, so leverage that).
• Clean up a lot of the documentation I made for the first approach and fill the README of the new package with relevant documentation.
• Keep adding translations.

Currently, I see we add the default label directly in the template, for example in BlockOptions.ts:

{editor.getLabelText('editor.blockOptions.delete') || 'Delete'}

I propose we treat all the default labels as translations. It will be easier to read, we can have all labels in one place, we could keep adding translations in another languages to give them out of the box and as a bonus if the user sets as the current language a language they are not providing, the keys will be shown instead, making it way easier for context translation.

So the example would look like this:

{editor.getLabelText('editor.blockOptions.delete')}

In my original approach, I added a i18n folder to each plugin, with the default locales for every language we wanted to add. We could start by only adding English for now.
Another advantage of this approach is that right now, if you want to modify a label in English, you have to provide a translation for all the labels, adding the new language. Treating the default labels as translations will allow us to override only the keys provided by the users.

Let me know your thoughts, I think having a TODO list will help us to stay organised.

[Darginec05]

@gloaysa

1. Yeah, TranslationManager is not used anymore, so it should be deleted
2. Agree
3. We can add editor.emit in setLanguage method in withTranslation when we change language
4. yes
5. yeap, we need to add translations for additional block option items in some plugins

[gloaysa]

The current state in this PR:

• All the issues above (minus adding missing labels) have been addressed.
• We now have a provider that will allow the use of useTranslations, wrapping the boilerplate code for the user. The provider is optional, the editor can also only be extended using withTranslations.

There's still a problem that don't know how to address. Changes on the language doesn't trigger a re-render of the Editor, so the new language selected is not reflected on it until the user interacts with the Editor.