Add initial i18n documentation

content/docs/i18n.mdx

@@ -0,0 +1,243 @@
+---
+id: i18n
+title: i18n
+description: Translate jsonforms
+---
+
+import I18nExample from '../../src/components/docs/i18n';
+
+:::note
+
+Please note that the renderer sets themselves are not yet translatable.
+You can find the current status here:
+https://github.com/eclipsesource/jsonforms/issues/1826
+
+:::
+
+The translate functionality of JSONForms is integrated into the core component.
+In order to translate JSONForms, you need to set a translation function and provide it to the JSONForms object:
+```ts
+const translator = (key, defaultMessage) => {
+  console.log(`Key: ${key}, Default Message: ${defaultMessage}`);
+  return defaultMessage;
+};
+
+const [locale, setLocale] = useState<'de'|'en'>('de');
+
+<JsonForms
+  i18n={{locale: locale, translate: translator}}
+  ...
+/>
+```
+
+The i18n prop consist of three components: `locale`, `translate`, `translateError`. 
+
+## `locale`
+
+Allows to specify the current locale of the application.
+This can be used by renderers to render locale specific UI elements (for example formatting of dates).
+
+
+## `translate`
+
+Allows to provide a translation function, which handles the actual translation.
+
+:::caution
+
+The translate function should be side effect free and should be stable (memoized) to avoid unnecessary re-renderings, i.e. the translate function should only change if there are new translations.
+
+:::
+
+
+The translate function has the following parameters:
+
+### `key`
+
+The key is used to identify the string, that needs to be translated.
+It can be set using the `UI Schema`, the `JSON Schema` or is generated by default based on the property path.
+
+#### UI Schema option
+
+The key can be set via the `i18n` UI Schema option:
+```json
+{ 
+  "type": "Control", 
+  "label": "name", 
+  "scope": "#/properties/name", 
+  "options": { 
+    "i18n": "customName" 
+  } 
+}
+```
+
+Therefore the translation will be invoked with `customName.label` & `customName.description`.
+
+#### JSON Schema
+
+The key can also be set with the custom JSON Schema `i18n` option:
+```json
+{
+  "name": { 
+    "type": "string", 
+    "i18n": "myCustomName" 
+  }
+} 
+```
+
+Therefore the translation will be invoked with `myCustomName.label` & `myCustomName.description`.
+
+#### Default: Property path
+
+Is none of the above is set, the property path will be used as the key.
+e.g. `name`.
+
+```
+{
+  properties: {
+    firstName: {
+      type: "string"
+    },
+    address: {
+      type: "object",
+      properties: {
+        street: {
+          type: "string"
+        }
+      }
+    }
+    comments: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          message: {
+            type: "string"
+          },
+        }
+      }
+    }
+  }
+}
+```
+
+The paths in the above example would be:
+- `firstName.label` & `firstName.description`
+- `address.street.label` & `address.street.description`
+- `comments.message.label` & `comments.message.description` (the path for arrays will not contain indices)
+
+### `defaultMessage`
+
+The default message is provided by JSONForms and can act as a fallback or could be translated.
+
+:::note
+
+If the defaultMessage is `undefined` it should not be modified and still return as `undefined` (and not an empty string or similar).
+JSON Forms will use `undefined  when the message could be skipped or another generic key could be tried. 
+
+:::
+
+### `values`
+
+The values can contain additional context, if the key of the string is not enough to determine the correct translation.
+For example all error translations will have the error as part of the values object.
+
+## Error Customizations
+
+TODO: Description
+
+#### `<i18nkey>.error.custom`
+
+If `error.custom` is set, just a single error will be output, no matter how many errors are present.
+The `translate` function is called for `error.custom`
+The `translateError` function is called for each error.
+By default it behaves like this:
+
+## `translateError`
+
+The `translateError` is called for every AJV error. 
+`translateError` is an optional parameter to the i18n object. Usually it is not expected to customize this option.
+By default error it works like this:
+
+`<i18nkey>` in the sections below refers to the key of the field (see `key` section above).
+
+### Evaluation order
+
+#### `<i18nkey>.error.<keyword>`
+
+e.g. `name.error.required`
+
+If no `error.custom` is set, the translator will look for a concrete message for a specific field and a specific error. 
+In the example above, the function will look for a `required` error on the `name` field.
+
+#### `error.<keyword>`
+
+e.g. `error.required`
+
+If no specific field error message is set, the translator will then look for an error message, that is independent of the field. 
+In the example case above, the function will look for a `required` error translation.
+
+#### Default error translator
+
+Next the translator will look for a default message, which is provided by the core framework.
+
+#### Default AJV error message
+
+If none of the above are set and no default error is available, the error message provided by AJV will be output.
+
+### Example
+
+If we have the following schema:
+```js
+{
+  phone: {
+    type: "string",
+    minLength: 10,
+    pattern: "^[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}$"
+  }
+}
+```
+And the order in which the error keys are evaluated is the following:
+- `phone.error.custom`: if this is set, the `pattern` and `minLength` error will be ignore and just this message is output
+- `phone.error.pattern` & `phone.error.minLength`
+- `error.pattern` & `error.minLength`
+
+## Enum translation
+
+Enum translations are a little different then the other control translations. 
+In order to translate enum values, you need to add one additional attribute to the translation for every value. 
+For example:
+Let's assume we have a field `Gender`, which has three possible values: 
+- `Male`
+- `Female`
+- `Other`
+
+If we now want to translate these, we need to reference them in the translation like this:
+```js
+gender: {
+  label: 'Geschlecht',
+  description: 'Das Geschlecht auswählen',
+  Male: 'Männlich',
+  Female: 'Weiblich',
+  Other: 'Divers'
+},
+```
+
+So the `label` attribute translates the `label` of the field, just like with any other control field. The same with the `description` attribute.
+All the other options translate the possible values of the enum.
+
+## Access translation in custom renderer sets
+
+If you want to access the translation function within a custom renderer set, you can use the JSONForms context for that:
+```
+const ctx = useJsonForms();
+
+const locale = ctx.i18n.locale;
+const translate = ctx.i18n.translate;
+const translateError = ctx.i18n.translateError;
+```
+
+With this you can for example change phone number patterns based on the current locale for validation.
+
+## Example
+
+<I18nExample />

content/pages/assets/support.module.scss

@@ -1,4 +1,4 @@
-h3 {
+.comparison_container h3 {
   font-size: 2rem;
   padding: 0;
 }

src/components/docs/i18n.js

@@ -0,0 +1,142 @@
+import React, { useMemo, useState } from 'react';
+import get from 'lodash/get';
+import {
+  materialCells,
+  materialRenderers,
+} from '@jsonforms/material-renderers';
+import Button from '@mui/material/Button';
+import { JsonForms } from '@jsonforms/react';
+
+const i18n = {
+  schema: {
+    properties: {
+      firstName: {
+        type: "string"
+      },
+      lastName: {
+        type: "string"
+      },
+      email: {
+        type: "string"
+      },
+      gender: {
+        type: "string",
+        enum: [
+          "Male",
+          "Female",
+          "Other"
+        ]
+      }
+    },
+    required: [
+      "email"
+    ]
+  },
+  uischema: {
+    type: "VerticalLayout",
+    elements: [
+      {
+        type: "VerticalLayout",
+        elements: [
+          {
+            type: "Control",
+            scope: "#/properties/firstName"
+          },
+          {
+            type: "Control",
+            scope: "#/properties/lastName"
+          }
+        ]
+      },
+      {
+        type: "Control",
+        scope: "#/properties/email"
+      },
+      {
+        type: "Control",
+        scope: "#/properties/gender"
+      }
+    ]
+  }
+}
+
+export const en = {
+  firstName: {
+    label: 'First Name',
+    description: 'The first name of the person',
+  },
+  lastName: {
+    label: 'Last Name',
+  },
+  email: {
+    label: 'Email'
+  },
+  gender: {
+    label: 'Gender',
+    Male: 'Male',
+    Female: 'Female',
+    Other: 'Diverse'
+  },
+  error: {
+    required: 'This field is required',
+  },
+};
+
+export const de = {
+  firstName: {
+    label: 'Vorname',
+    description: 'Der Vorname der Person',
+  },
+  lastName: {
+    label: 'Nachname',
+  },
+  email: {
+    label: 'Email'
+  },
+  gender: {
+    label: 'Geschlecht',
+    Male: 'Männlich',
+    Female: 'Weiblich',
+    Other: 'Divers'
+  },
+  error: {
+    required: 'Dieses Feld muss ausgefüllt werden.',
+  },
+};
+
+const I18nExample = () => {
+  const [locale, setLocale] = useState('de');
+
+  const createTranslator = (locale) => (key, defaultMessage) => {
+    return get(locale === 'en' ? en : de, key) ?? defaultMessage;
+  };
+
+  const translation = useMemo(() => createTranslator(locale), [locale]);
+
+  const switchLocale = () => {
+    if(locale === 'en') {
+      setLocale('de');
+    } else {
+      setLocale('en');
+    }
+  };
+
+  return (
+    <div>
+      <JsonForms
+        schema={i18n.schema}
+        uischema={i18n.uischema}
+        i18n={{locale: locale, translate: translation}}
+        renderers={materialRenderers}
+        cells={materialCells}
+      />
+      <Button onClick={switchLocale} color='primary' variant='contained'>
+        Switch language
+      </Button>
+      <br />
+      Current language: {locale}
+    </div>
+  );
+};
+
+export default I18nExample;