Skip to content

docs: suggesting translations in context for community projects (pitch tolgee/tolgee-platform#3780, scope E) - #1144

Open
Anty0 wants to merge 4 commits into
jirikuchynka/community-translations-docsfrom
jirikuchynka/community-sdk-suggestions-e
Open

Anty0 wants to merge 4 commits into
jirikuchynka/community-translations-docsfrom
jirikuchynka/community-sdk-suggestions-e

Conversation

@Anty0

@Anty0 Anty0 commented Sep 20, 2026

Copy link
Copy Markdown
Member

Docs for in-context suggestions, scope E of pitch tolgee/tolgee-platform#3780 (community translation v2.0, SDK and browser plugin).

Held until the release. The feature is not released yet (platform tolgee/tolgee-platform#3930, SDK tolgee/tolgee-js#3539, browser plugin). Do not merge before those ship.

Depends on #1130. This PR targets jirikuchynka/community-translations-docs, because the new owner page links into the Community Translation page added there. Merge #1130 first, then retarget this PR to main.

What it delivers

  • New page platform/projects_and_organizations/community_translation_in_context.mdx for owners of public projects: what to configure in the project (public project, Suggestions mode) and on the website (apiUrl and projectId, no apiKey, SDK kept up to date), what contributors need (Tolgee account and the Tolgee Tools plugin), and what they can and can't do in the dialog.
  • js-sdk/in_context.mdx: new section "Suggest translations in context" (the Save / Suggest / Save & suggest button, what happens when one change fails, suggestions under each language with the actions per permission, the suggest-only dialog, troubleshooting including the plugin's reconnect prompt). Also a short subsection on signing in to the plugin with a Tolgee account instead of an API key, which the owner page depends on and which was not documented yet.
  • suggestions.mdx: with Suggestions mode off, the API now rejects new suggestions with suggestions_disabled (HTTP 400) while existing ones stay manageable; deleting your own suggestion is a separate permission, also for API keys and connected applications.
  • options.mdx: projectId is also needed for plugin sign-in.

Left out on purpose (optional in the pitch, undecided): in-context commenting, key description in the dialog, "Suggest instead".

Open before merge

The dialog UI was built in parallel, so these need a pass against what actually ships.

  • Release blocker — TODO_PLATFORM_VERSION: the minimum Tolgee platform version, in the owner page's "Prepare your project" and in the in-context troubleshooting. The dialog's own MINIMAL_PLATFORM_VERSION is deliberately left at v3.42.0, because every new field degrades on an older server rather than breaking, so the docs are the only place this requirement is stated.
  • Release blocker — TODO_SDK_VERSION: the minimum @tolgee/web version carrying suggestions in the dialog, in the in-context troubleshooting.
  • Both placeholders ship as literal text until filled in: grep -rn "TODO_SDK_VERSION\|TODO_PLATFORM_VERSION" platform js-sdk
  • Six screenshots: dialog with the suggestion list under a language; the "will be sent as a suggestion" note with the Save & suggest button; the suggest-only dialog; a partial-failure error on a field; the plugin popup with Connect to Tolgee; the advanced permissions Suggestions group with the delete-own row
  • Final labels from the dialog: accept, accept and decline others, decline, delete and "show more" are described in plain words until the labels are final; confirm Save / Suggest / Save & suggest
  • If "show more" is cut, fix "lets you load the rest" in "Review suggestions in the dialog"
  • Re-check the partial-failure paragraph against the shipped behaviour
  • Plugin reconnect wording (Reconnect to enable suggestions, Sign in again) against the released plugin
  • Label of the delete-own permission in advanced permissions (described without quoting it for now)
  • Owner page: verify the consent step wording and the project ID URL example in the real flow

Checked locally with npm run build (broken links and anchors throw).

  • Badge: confirm the short link https://docs.tolgee.io/translate-with-tolgee 301s to the page on the deploy preview (the redirect lives in static/_redirects; docusaurus serve ignores that file, so it cannot be proven locally)
  • Badge: the slug is provisional pending the team's view. If it changes, it is 4 mechanical edits — the front matter, the _redirects line and the two snippets

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant