# Onboarding agencies

Bring an external agency or freelance translator into a project with the right access, a brief, a reviewer on your side, and a clean offboarding.

Canonical: https://comvi.io/docs/platform/recipes/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](/docs/platform/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](#brief-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](/docs/platform/recipes/translator-review-workflow).

6. **Notify the reviewer (optional)** with a [webhook](/docs/platform/integrations/webhooks)
   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`

```markdown
# 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](/docs/platform/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](/docs/platform/import-export)
   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](/docs/platform/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 management](/docs/platform/team-management): Roles, restrictions, invitations.
- [Translator and reviewer workflow](/docs/platform/recipes/translator-review-workflow): How agency work gets approved.
- [Glossaries](/docs/platform/glossaries): Populate before the agency starts.
- [Import & export](/docs/platform/import-export): The file hand-off path.