Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: tolgee SDK v6 #793

Merged
merged 17 commits into from
Jan 8, 2025
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
feat: tolgee SDK v6
Štěpán Granát authored and stepan662 committed Jan 6, 2025

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
commit 536b5a4bdec900719f9a8fec555147596322f11f
2 changes: 1 addition & 1 deletion docs.js
Original file line number Diff line number Diff line change
@@ -30,7 +30,7 @@ const docs = [
versions: {
current: {
banner: 'none',
label: '5.x.x',
label: '6.x.x',
},
},
},
6 changes: 6 additions & 0 deletions js-sdk/migration_to_v6.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
id: migration-to-v6
title: Migration to v6
---


53 changes: 53 additions & 0 deletions js-sdk_versioned_docs/version-5.x.x/about.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
id: about
title: Overview
slug: /
description: 'Tolgee SDK provides the functionality of an i18n library and helps you with formatting, interpolation, or language detection. '
---

import { ScreenRecording } from '../../platform/shared/_ScreenRecording';

Tolgee SDK provides the functionality of an i18n library and helps you with [formatting](./formatting), interpolation, and [language detection](./language#language-detection).
The SDK also allows you to connect to the [Tolgee Platform](../../platform/). It enables you to implement [in-context translation](./in-context) which also helps you generate one-click screenshots and edit translations directly in your app.

## In-context Translation

In-context translation helps you speed up development by saving you from tedious localization tasks. Using the Tolgee SDK, you can implement in-context translation. Learn more about in-context translation and how to implement it in your local development environment in [this documentation](./in-context).

<ScreenRecording>
<source src="/in-context.mov"></source>
</ScreenRecording>

You can also enable in-context translation in the production version of your web application. Set up the [Tolgee Tools](https://chrome.google.com/webstore/detail/tolgee-tools/hacnbapajkkfohnonhbmegojnddagfnj) to use in-context translation in production.

<ScreenRecording>
<source src="/in-context-production.mov"></source>
</ScreenRecording>

## Automated Screenshots Generation

To help translators understand the exact context of the translation, you can now add screenshots. Generate one-click screenshots with in-context translation or the [Tolgee Tools](https://chrome.google.com/webstore/detail/tolgee-tools/hacnbapajkkfohnonhbmegojnddagfnj) extension.

<ScreenRecording>
<source src="/in-context-screenshot.mov"></source>
</ScreenRecording>

## Automatic Context Collection

The SDK automatically collects additional context about the layout of the keys on the page. This context allows the Tolgee Translator to provide you with better results, utilizing ChatGPT under the hood.

### What data are collected and when?

Every time you save a translation through the in-context translation dialog box, the SDK sends a list of keys currently present on the page to the Tolgee platform. The platform then tracks the relationships between the keys based on thier order of appreance across different pages.

### Is this safe, and what about data leaks?

We only collect information about the order of the translations, which are already present on the platform. This order information helps the model better understand their relationships. We do not collect any additional information from your page.

## Review translations

Your team can review the translations directly in your app, make any necessary changes, and mark these translations as reviewed. This helps you set up a workflow for translation, speeding up the process and resulting in faster development.

<ScreenRecording>
<source src="/in-context-review.mov"></source>
</ScreenRecording>
15 changes: 15 additions & 0 deletions js-sdk_versioned_docs/version-5.x.x/api/core_package/about.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
id: about
title: About
description: "Tolgee core package is platform agnosting and aims to provide universal basis for all other packages from Tolgee SDK."
---

## Tolgee core

Tolgee core package is platform agnosting and aims to provide universal basis for all other packages from Tolgee SDK.

It exports these basic parts:

- [`TolgeeCore`](./tolgee#tolgeecore) instance creator
- [`FormatSimple`](./format-simple) plugin
- [Other tools](./other-tools)
84 changes: 84 additions & 0 deletions js-sdk_versioned_docs/version-5.x.x/api/core_package/events.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
---
id: events
title: Core Events
sidebar_label: Events
---

Tolgee events which can be listened through `tolgee.on` method.

### language

Emitted on language change.

```ts
tolgee.on('language', handler: ListenerHandler<string>)
```

### pendingLanguage

Emitted on language change. Before languages are loaded (when tolgee is running).

```ts
tolgee.on('pendingLanguage', handler: ListenerHandler<string>)
```

### loading

Emitted on loading change. Changes when tolgee is loading some data for the first time.

```ts
tolgee.on('loading', handler: ListenerHandler<boolean>)
```

### fetching

Emitted on fetching change. Changes when tolgee is fetching any data.

```ts
tolgee.on('fetching', handler: ListenerHandler<boolean>)
```

### initialLoad

Emitted when `run` method finishes.

```ts
tolgee.on('initialLoad', handler: ListenerHandler<void>)
```

### running

Emitted when internal `running` state changes.

```ts
tolgee.on('initialLoad', handler: ListenerHandler<boolean>)
```

### cache

Emitted when cache changes.

```ts
tolgee.on('cache', handler: ListenerHandler<CacheDescriptorWithKey>)
```

### update

Emitted when any key needs (or might need) to be re-rendered. Similar to `tolgee.onNsUpdate`,
except we intercept all events, not just selection.

```ts
tolgee.on('update', handler: ListenerHandler<void>)
```

### error

Emitted when there is an error. You can intercept different types of errors, connected to fetching language data, detecting language or loading/storing language, you can filter them by `name` property on the error, which can be:
- `RecordFetchError` - error when fetching translations record, you can also read `language` and `namespace` properties, to see which record has failed
- `LanguageDetectorError` - error when detecting language through language detector plugin
- `LanguageStorageError` - error when loading/saving language through language storage plugin

```ts
tolgee.on('error', handler: ListenerHandler<TolgeeError>)
```

Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
id: format_simple
title: FormatSimple
sidebar_label: FormatSimple
slug: format-simple
description: Super light formatter, which will enable you to pass variables into translations. It is a subset of ICU format.
---

Super light formatter, which will enable you to pass variables into translations.
It's a subset of Icu format.

## Usage

```ts
import { FormatSimple } from '@tolgee/core';

const tolgee = Tolgee()
.use(FormatSimple())
.init(...)
```

## Syntax

Passing variable:

```ts
f('Martin is {age} years old.', { age: 10 });
// Martin is 10 years old
```

You can also escape special characters by wrapping them into `'`, it works the same as in Icu standard and it only
acts like escaping character when it's followed by escapable character ("{`). It doesn't have to be closed (then all
rest of the translation is escaped).
```ts
f("This is escaped text: '{age}'");
// This is escaped text: {age}

f("This is also '{fine}");
// This is also {fine}

f("This will work 'as expected'");
// This will work 'as expected'
```
That's it! We've tried to do this format as simple as possible so the parser doesn't bloat your bundle.
If you need advanced features use [`@tolgee/format-icu`](/platform/translation_process/icu_message_format) package.
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
---
id: observer_options
title: Observer options
sidebar_label: Observer options
slug: observer-options
---

Tolgee Observer options which are part of [tolgee options](./options). Allows you to influence `ObserverPlugin` if present.

### targetElement

Element where wrapped strings are expected in development mode.

```ts
targetElement: Node;
```

Default: `document`

### fullKeyEncode

Encode full key info into the wrapped translation (read more about [wrapping](/js-sdk/wrapping)). This option allows you to wrap translations on the server and then unwrap on the client. The option is important for the wrapping side (server), the unwrapping side can handle both cases.

> By default Tolgee encodes only key indexes and that requires the usage of the same instance for wrapping and unwrapping.
Default: `false`


### tagAttributes

Tolgee is able to watch also for wrapped localization strings in attributes of DOM elements.
These attributes must be specified in these configuration properties.

```ts
tagAttributes: Record<string, string[]>;
```

Default:

```ts
tagAttributes: {
textarea: ['placeholder'],
input: ['value', 'placeholder'],
img: ['alt'],
'*': ['aria-label', 'title'],
}
```

### highlightKeys

By default, in development mode, when you move mouse over an element containing translated text and key ALT is down, this element is highlighted by changing its background color. To modify the key use highlightKeys property.

```ts
highlightKeys: ModifierKey[];
```

Example:

```ts
import { ModifierKey } from '../clients/js/packages/core/lib/index';

highlightKeys: [ModifierKey.Shift, ModifierKey.Alt];
```

Default: `[ModifierKey.Alt]`

### highlightColor

Highlighter border color.

```ts
highlightColor: string;
```

Default: `rgb(255 0 0)`&nbsp;&nbsp;<div style={{
border: "5px solid rgb(255 0 0)",
borderRadius: "4px",
width: "20px",
height: "20px",
display: "inline-block",
verticalAlign: "middle"
}}></div>

### highlightWidth

Border width of highlighter.

```ts
highlightWidth: number;
```

Default: `5px`

### restrictedElements

Array of elements in which you don't want Tolgee to replace wrapped strings.

```ts
restrictedElements: string[];
```

Default: `['script', 'style']`

### inputPrefix and inputSuffix

Only for `TextObserver`

In development mode, strings to be translated are wrapped by `@tolgee/core` library at first and then parsed and replaced with
translated value. This mechanism is called [wrapping](/wrapping.mdx).

`inputPrefix` is inserted before the encoded string and `inputSuffix` is inserted after the string. By those 2 strings
Tolgee recognises strings, which are meant to be translated, so its good idea to make them unique enough not to collide
with any other strings, which can appear in DOM.

Example:

```typescript
inputPrefix = '%-%tolgee:';
inputSuffix = '%-%';
```

These strings are unique enough to not clash with any other strings in your DOM, so it will not break your document.

```ts
inputPrefix: string;
```

### passToParent

There are elements which can contain wrapped string to be translated, but user is not able to click on them. For example
an option of `select` HTML element cannot be used for capturing click even with `ALT` down. For these reasons you can
configure Tolgee to "pass" these strings to parent and listen for click events on the parent.

```ts
passToParent: (keyof HTMLElementTagNameMap)[] | ((node: Element) => boolean);
```

Default: `["option", "optgroup"]`
Loading