@resys/understood NPM

understood

Simple translation editor.

Usage

Example:

import { Understood } from '@resys/understood';
const translations = { table: { en: 'Table', et: 'Laud' } };
<div style={{ height: 800 }}>
  <Understood
    initialTranslations={translations}
    format='keyToLanguage'
    initialLanguages={['en', 'et']}
    onChange={newTranslations => console.log(newTranslations)}
    onMetadataChange={newMetadata => console.log(newMetadata)}
    onChangeItem={(key, language, text) => console.log(`Changed '${key}' for language '${language}' to '${text}'`)}
  />
</div>

It is important that <UnderstoodTableEditor/> is wrapped in a fixed-height container. This is necessary because the editor uses react-virtualized to avoid rendering too many DOM nodes at once, and react-virtualized works off of fixed sizes.

See more examples here.

Props

Property	Type	Required?	Description
initialTranslations	`{ [string]: { [string]: string } }`	✓	Translations object that is used to initialize state. Note that it is preferred that you provide the translations once and then keep the object the same if you don't do any external mutations do them. This is because every time object changes, the translations need to be parsed again, for example for problematic translations. However, if you provide the same object that you received from e.g. `onChange` back into this prop, it won't be parsed again.
format	'keyToLanguage' or 'languageToKey'	✓	Use 'keyToLanguage' if your translations are in the format of `{ key: { language: text } }`; use 'languageToKey' if your translations are in the format of `{ language: { key: text } }`
availableLanguages	Array		Languages that are available to be translated. If not set, languages are extracted from the translations data
initialLanguages	Array		Initial languages to show. If not set, the first two available languages are shown.
onChange	Function		Called whenever a translation is changed. The full translations object is passed into this function: `(translations): void`
onMetadataChange	Function		Called whenever metadata is changed. If not given, will disable UI elements that try to mutate metadata.
onChangeItem	Function		Called whenever a translation is changed: `(key, language, text): void`
initialMetadata	See metadata section		This is used to initialize metadata state. Not that it is preferred that you provide this prop once and then keep it the same. This is because every time the object changes, it needs to be parsed again, for example for problematic translations. However, if you provide the same object that you received from e.g. `onChange` back into this prop, it won't be parsed again.
components	See custom components section		Custom components. Props that are passed to component are documented as `React.Component<PROPS>`.
plaintextTranslation	`(translation: string) => string`		If you use special formatting in your translations (e.g. Markdown), provide this function to turn it into regular plaintext. This allows search to work and will also be used to render cells in the table, unless custom `TranslationCell` component is provided.

Metadata

Metadata is used internally for flagging translations, but you can also provide external metadata to provide context information or to use in your own custom components.

Editor uses the following metadata structure to provide context information:

type Metadata = {
  key: {
    [key: string]: {
      description?: string; // Description for the given translation key
      needsWork?: boolean; // true when user has marked a translation key as needing work
    }
  },
  language?: {
    [language: string]: {
      longName?: string; // Long name for the language, shown in place of the language key when provided
      flag?: string; // Semantic UI flag to show next to the language name
    }
  }
};

You can add your own custom metadata to this structure if you want to.

Custom components

You can provide custom components to change parts of the UI behaviour. For example:

<Understood
  initialTranslations={translations}
  format='keyToLanguage'
  components={{
    Editor: ({ value, onChange }) => <Input value={value} fluid onChange={e => onChange(e.currentTarget.value)}/>
  }}
/>

This would change the translation editor from the default TextArea into an Input.

Editor

Displays the translation editor. For each visible language, there will be an instance of the editor rendered.

interface EditorProps {
  value: string;
  onChange: (value: string) => void;
  metadata: KeyMeta | undefined;
  translationKey: string;
  language: string;
}

TranslationCell

Displays translation cells in the table.

interface TranslationCellProps {
  value: string;
  metadata?: KeyMeta;
}

Run the demo

yarn storybook

Run tests

yarn test:watch

react-component translation

immer react-virtualized semantic-ui-react

@dialob/dialob-composer

2.1.1

12 months ago