In-context translating

In-context translating lets you edit translations directly in your running app. Hold Alt/Option, click a string, and change it in the Quick translation dialog without searching for its key in Tolgee. This page shows how to set it up for local development, take one-click screenshots, use it on production through the Tolgee Tools browser plugin, and suggest or review translations in the dialog.

For local development, supply apiUrl, apiKey options (see Integration) and DevTools plugin. If you set everything properly, you can use in-context translating:

1. Press and hold Alt/Option key
2. Navigate mouse over any translation on your website
3. It should get highlighted
4. Click on it to open Quick translation dialog
5. You can edit translations (changes will get stored to Tolgee platform)

NOTE: If you use Tolgee without any integration, make sure you call run method.

One-click screenshots

To generate screenshots automatically, you have to have installed Tolgee Tools extension for Google Chrome or add-on for Mozilla Firefox. With this tool, you can generate screenshots by clicking camera icon in Tolgee UI translation dialog.

info

DevTools are automatically omitted in production builds (based on NODE_ENV variable).

In-context on production

If you want to enable in-context on production build, there are two options:

1. Tolgee Chrome/Firefox plugin

The Tolgee Tools extension for Google Chrome or Mozilla Firefox turns in-context translating on for a production site. The page itself ships no credential. The extension gives the SDK a credential in one of two ways. The SDK then switches to development mode, and the extension loads the in-context editor for you.

warning

Your apiKey should stay private and never be included in Tolgee configuration on production.

• Local development: You can pass apiKey directly in your Tolgee configuration.
• Production: Sign in with your Tolgee account in the Tolgee Tools extension, or apply an API key there.

Sign in with your Tolgee account

This is the recommended way. The user signs in with their Tolgee account, Tolgee shows a consent screen, and the extension keeps a short-lived token. The page never sees it.

1. Install Tolgee Tools

2. Go to the production version of your website

3. Click on Tolgee Tools extension and choose Connect to Tolgee

   

4. Approve the access on the Tolgee consent screen

   

5. In-context translating should work

   

What your site has to provide:

• projectId in the Tolgee configuration. The sign-in is bound to one project, and the extension reads which one from the page. See the projectId option.
• @tolgee/web 7.2.0 or newer. On an older SDK the extension asks for an update and offers the API key way instead.
• apiUrl in the configuration if you use a self-hosted Tolgee. Otherwise the user fills it in the extension.

How it works: the extension holds the token in its own service worker. The SDK sends every Tolgee API request to the extension, which adds the token, performs the request and returns the response. Screenshots are captured and uploaded by the extension too. A page can only reach the project it declares, on the server the user signed in to. The sign-in stays valid until the user signs out in the extension, or until it goes 30 days without use.

If the user has no access to the declared project, the consent screen says so and in-context editing does not work on that site for that account. The token still cannot do more than the user is allowed to do.

Signing in is also how community contributors work on a public project: they have no API key and no edit rights, and the dialog lets them suggest translations instead. On a self-hosted server the operator has to turn the browser extension on first (Tolgee v3.230.0 or newer).

Apply an API key

The older way still works. Click on Tolgee Tools extension and apply a Project API Key. With an SDK that supports the sign-in, the key stays in the extension as well, and requests go through it the same way. On an older SDK the key is written into the page's session storage and the page sends its own requests with it.

You can also check Step-by-step tutorial

A few notes about Tolgee Tools plugin

• The in-context switch in the popup only turns alt+click editing on or off for the current page. It does not end the sign-in. Use Sign out for that, see how to end the access.
• Plugin will supply apiUrl from Tolgee configuration if it's present (if not you can fill it manually).
• Plugin changes its icon to pink if Tolgee is present on the page or if credentials are set.

2. Using InContextTools instead of DevTools

DevTools are automatically omitted in production build (based on NODE_ENV variable), if you want to enable In-context unconditionally, you can use InContextTools (from @tolgee/web/tools package).

Note that InContextTools will significantly increase your bundle size, so we recommend using dynamic import and only including them when needed.

warning

In-context on production should be always behind some authentication or in a private network. Make sure you are not exposing your credentials publicly.

// initialize tolgee without DevTools
const tolgee = Tolgee()
  .use(FormatSimple())
  .init({
    ...
  });

// include in-context tools only if needed
if (shouldIncludeInContextTools) {
  import('@tolgee/web/tools').then((module) => {
    tolgee.addPlugin(module.InContextTools())
  })
}

Using parts of InContextTools functionality

InContextTools (or DevTools in development) are a combination of multiple plugins, which you can include independently, check InContextTools documentation for more info.

Suggesting Translations in Context

Not everyone who spots a wrong string should be able to change it. A translator may be allowed to edit German but only propose changes to the reviewed English copy, and a community contributor on a public project can't edit anything at all. They still see the string in its real context, which is the best place to notice that it is wrong.

When the project has suggestions enabled, the Quick translation dialog lets you propose a change in every language where you are allowed to suggest but not to edit. A suggestion doesn't change the live translation. It waits until a reviewer accepts it.

Saving, Suggesting, or Both

Permissions in Tolgee are set per language, so the dialog decides for each language field what happens with your change. For example:

• You can edit the language, so the change is saved as the translation.
• You can only suggest in the language, so the change is sent as a suggestion. The same happens when the project protects reviewed translations, the translation is already reviewed, and you are not allowed to change its state.
• You can do neither, so the field is read-only.

A field whose change will become a suggestion says so under the input before you submit, so you always know what a click will do. When the reason is the project's protection of reviewed translations, the note says that too. If you clear a suggest field instead of rewriting it, the note tells you the field is left unchanged, because an empty suggestion can't be sent.

The dialog also shows the key's description under the key name, when the key has one. It is the quickest way to find out what a string is for before you propose new wording.

The dialog keeps a single button, and its label follows the fields you have changed.

Button	What happens to your changes
Save	All of them are saved as translations
Suggest	All of them are sent as suggestions
Save & suggest	Some are saved, the others are sent as suggestions

For example, you fix a typo in German, which you translate, and reword the English source text, which only reviewers may touch. The button reads Save & suggest. One click stores the German translation, sends the English change as a suggestion, and closes the dialog.

The saved fields are written first, and the suggestions go out only once that has succeeded. So if the save fails, nothing is suggested either, and you can correct the form and submit it again without Tolgee rejecting your suggestions as duplicates.

If a suggestion itself fails, the dialog stays open with the error under the field it belongs to. The saved fields and the other suggestions stand, so you only fix the one that failed. A typical cause is proposing text that someone has already proposed, because Tolgee doesn't accept a suggestion that already exists on the translation.

Reviewing Suggestions in the Dialog

Reviewers usually judge a suggestion better when they see it where it will appear. Under each language field, the dialog lists the three most recent pending suggestions with their authors, and Show more loads ten more at a time. Each one shows who wrote it and how long ago, counted from now for the first month and as a date after that.

Each suggestion carries the actions you are allowed to use.

• A check mark icon accepts the suggestion. Its tooltip reads Accept or, when accepting can also dismiss the competing suggestions, Accept only, so the two outcomes can't be confused.
• A cross icon declines it.
• The ⋮ menu next to them holds Accept and decline others and Delete.

What you can do with a suggestion depends on your permissions for that language.

Action	Who can do it
Accept the suggestion, or accept it and decline the others	Users who can edit translations and change their state in the language
Decline the suggestion	Users who can change the translation state in the language
Delete the suggestion	Its author, if they have the permission to delete their own suggestions, or anyone who can manage suggestions in the language

Accepting a suggestion replaces the translation and refreshes the field in the dialog. Read more about the accept actions in Translation Suggestions.

The dialog shows only suggestions that are waiting for a decision. To look at accepted or declined suggestions, or to reverse a decision, open the key in the Tolgee platform.

Using the Dialog with Suggest-Only Permissions

When suggesting is all you are allowed to do, the dialog shows only what you can use. You see the translations, the suggestions on them, the key's screenshots, and the Suggest button. Controls for translation state, tags, plural forms, character limit, and screenshot upload are hidden.

The dialog below belongs to such a user. Both fields carry the suggestion note, the pending Czech suggestions have no accept or decline icons, and the only action is Suggest.

A suggestion always belongs to an existing key. If the string you clicked has no key in the Tolgee project yet, you can't suggest a translation for it, and someone with permission to create keys has to add the key first.

Troubleshooting Missing Suggestions

When the dialog shows nothing related to suggestions, check these causes first.

• Suggestions mode is turned off in the project settings.
• The website runs a version of @tolgee/web older than 7.3.0. The browser plugin loads the dialog in the version the website uses, so updating the plugin doesn't help. The website has to update the SDK.
• Your self-hosted Tolgee server is older than v3.230.0, or it hasn't turned the browser extension on. On such a server the plugin can't sign you in at all and fails with an authorization error.

When you see the suggestions of others but the dialog never offers Suggest to you, first check whether you can edit the language. Where you can edit, your change is saved directly, so there is nothing to suggest. The one exception is a reviewed translation on a project that protects reviewed translations, which is sent as a suggestion when you can't change its state.

If you can't edit either, the dialog tells you which of the two is missing. When your account has the permission but the credential the page uses doesn't carry it, a note under the field says so and points at the fix: sign in again in the plugin, or use an API key with more permissions. When your own account doesn't have the permission in that language, the field is simply read-only, since no key and no new sign-in would change that. Ask someone who manages the project.

The plugin also checks this by itself. If your account has permissions that the sign-in on this page doesn't include, its popup shows the alert The Tolgee plugin is missing some permissions with a Sign in again button. You stay connected if you close the alert instead.

Modals, popovers and other focus-stealing elements

Some elements like modals or popovers can steal focus from the Tolgee dev tools, so you can't type in the translation input fields.

Fortunately, you can still use the dev tools by opening them in a separate popup window by clicking the icon next to the Quick translation dialog title.

Your browser might block the popup, so you have to allow it.