Onboarding agencies

Invite external translators into the editor when you can; fall back to a file hand-off when the agency will not leave its own tooling.

Model	The agency	Use when
In-editor	Signs in to Comvi and edits directly	Ongoing relationship, live collaboration, TM and glossary in reach
File hand-off	Translates an export in its own tool; you import the result	One-off projects, or an agency committed to its own tooling

Invite into the editor

1. Invite each person from Organization → Members with Invite member, one invite per person. Give them the Translator role: they can create and edit values, run machine translation and comment, but cannot approve, touch keys or namespaces, or import or export. See Roles & permissions.

2. Restrict to one project with Restrict to project on the invite. A member scoped to a single project does not count against the plan’s member limit. There is no namespace-level access, so scoping an agency to marketing is a line in the brief and a filter they set themselves.

3. Restrict to the contracted languages with Restrict to languages, which appears once a project is selected, or later from Organization → Members → Change role or Settings → Project Access → Change role & languages.

4. Share the brief from the template.

5. Assign a reviewer on your side. Every value the agency saves lands as Needs Review, and an internal Editor moves it to Translated. See Translator and reviewer workflow.

6. Notify the reviewer (optional) with a webhook on translation.created and translation.updated; the agency’s first pass is nearly all created events.

An invitation is valid for 7 days. Resend sends the same link without extending the window and refuses once expired; cancel an expired invitation and send a new one. A person who already has a Comvi account is added immediately with a notification email.

Brief template

brief.md

# Project brief: <Project name>

## Product
- What it is: <one sentence>
- Who uses it: <audience, formality level>
- Live at: <staging + production URLs>

## Voice and tone
- Formal / casual: <pick one, give examples>
- Humor / wit: <yes / no>
- Brand terms that must NOT be translated: <list; also in the glossary with Translatable unchecked>

## Scope
- Languages in scope: <list>
- Namespaces in scope: <list>
- Deadline: <date>
- Approximate word count: <N>

## How to work
- Check the translation memory panel first. Accept a 100% match unless the context differs.
- Read the key's Internal notes and AI translation context before translating.
- Glossary terms are highlighted in the source. Use the term marked Correct, never one marked Forbidden.
- ICU placeholders ({name}, {count, plural, …}) must appear in every target unchanged.
- Flag an ambiguous source string as a comment on the key rather than guessing.

## Contact
- Questions: <Slack channel / email>
- Reviewer: <name, timezone>

Before they start

• Populate the glossary with product names, UI labels and untranslatable brand terms. Leave Translatable unchecked on the ones that must appear unchanged, so the Non-translatable Modified check flags any target that changes them. See Glossaries.
• Fill in the key context fields. Team-facing notes go in Internal notes (not sent to MT), anything a provider should see in AI translation context (sent to MT).
• Warm the translation memory. It is organization-wide, so other projects’ work is already available. For a language new to the organization, the agency’s first few hundred translations become the matches for the rest.

During the engagement, read the Languages page weekly: the bar per language splits into Translated, Needs Review and Not Translated. A Needs Review count that grows faster than it shrinks means the bottleneck is your reviewer. Answer comments quickly; a translator with an unanswered question guesses or stops.

File hand-off

1. Export the scope. Open Export, pick the languages and namespaces, set the status filter to Not Translated with empty values included. Formats are JSON and i18next v4 JSON; XLIFF, CSV and PO are listed as coming soon, so an agency that requires XLIFF needs a converter on its side.

2. Write the brief with the format rules added: ICU placeholders, line breaks, escaping, one worked source and target pair.

3. Check what comes back: UTF-8 only, every source placeholder present in the target, source and target not swapped, file structure unchanged. Comvi does not verify placeholder parity on save or on import.

4. Import, then send the batch to review. An import writes every non-empty value as Translated with you as reviewer. Select the imported rows on the Translations page and use Status → Mark as Needs Review.

5. Pay from the approved count after review rather than raw delivery, and say so in the brief.

Offboard

• Remove the member from Organization → Members on the last day.
• Export a snapshot of the languages they worked on. Per-key history already records who changed what; an export is easier to read later.
• Delete any API key you issued them under API keys.
• Note in the project description who covered which languages.

Do not give an agency Editor or Manager

Both roles can approve, so the agency would sign off its own work. For the same reason, do not hand out a write API key to someone who only needs the editor.

Next steps

Team managementRoles, restrictions, invitations.

Translator and reviewer workflowHow agency work gets approved.

GlossariesPopulate before the agency starts.

Import & exportThe file hand-off path.