Translation agency using ShipifyAI

ShipifyAI was originally designed for software teams, but the same workflow maps cleanly onto any organisation that produces text artefacts in a versioned repository, has a board of work items, and announces results on a chat channel. A translation agency fits the model unusually well. Localisation work has already been a Git-friendly discipline in the software industry for years, with XLIFF, PO, and Markdown files passing through pull requests. ShipifyAI extends that pattern to general-purpose translation work and adds an AI drafting layer that runs under linguist supervision rather than as raw machine translation.

This article walks through the setup of ShipifyAI for a fictional mid-sized translation agency. It covers how to structure the Jira board, the working repository, and the Slack channel, how to write a `CLAUDE.md` tailored for translation, and which MCP servers to allow so that the AI can draft translations consistently with the agency's translation memory and client glossaries.

The scenario

The agency has a head of localisation who owns quality and process, several senior translators who specialise in specific language pairs and domains, a few junior linguists who do first-pass work under review, and project managers who handle client intake and delivery. The agency works mostly in EN to and from PL and DE, and covers a mix of literary, technical, marketing, and legal-adjacent translation. Each client has its own glossary, its own brand voice, and its own delivery format. The head of localisation wants to use AI for first-pass drafting and consistency checks while keeping a human linguist in the review seat for everything that goes to a client.

ShipifyAI's role is to take a structured task from Jira, hand it to Claude with the agency's translation memory, the client's glossary, and the client's style guide, produce a translated draft committed to the repository, open a pull request for linguist review, and post the link in Slack. Nothing leaves the agency without a senior linguist approving the work into the client's chosen delivery channel.

Setting up the document repository

The agency uses GitHub as its working repository, with private access restricted to the localisation team. The repository is structured to mirror the agency's client portfolio. Each top-level directory is a single client, with branch protection restricting access to the linguists assigned to that client. Within each client directory there is a `source` subdirectory containing the original-language files, a `target` subdirectory containing the translated files, a `glossary` file listing the client's approved terminology and do-not-translate items, and a `style-guide.md` describing the client's voice. Project-level metadata such as language pair, deadline, and word count lives in YAML front matter on each task.

The agency keeps a shared `tm` directory at the repository root, containing the agency's segmented translation memory exports in TMX format. A shared `glossaries` directory at the root holds cross-client terminology that is not specific to any single engagement. CI runs format validation on every push: XLIFF and PO files must parse cleanly, placeholders must be preserved, and segment counts must match between source and target.

Source files come in many shapes. Software localisation work uses XLIFF and PO files. Marketing work uses Markdown with YAML front matter. Document translation arrives as Markdown. The ShipifyAI CLI writes its translations back in whichever format the source arrived in — XLIFF segments back into XLIFF, PO entries back into PO, Markdown sections back into Markdown — and for any of these the plain-text shape means Git diffs are meaningful and the AI can produce changes the same way it produces code. What the agency does with that output once a linguist has reviewed it is the agency's own call, and outside ShipifyAI's scope: rendering Markdown into Word or PDF through a CI pipeline using the client's house template, exporting XLIFF back to the client's translation management system, or shipping the file as-is.

A key difference compared with the software scenario is that pull requests in the translation agency are not a gate to merging. They are a delivery channel. The AI's deliverable is the translated draft itself, sitting on a feature branch, with a pull request that gives the linguist a structured place to read the diff segment by segment, mark changes, and pick up the work. Most drafts are never merged into the default branch at all. The linguist reviews the draft on the branch, exports the final text into the agency's CAT tool, the client's translation management system, or the client's delivery format, and that completes the task. The branch can then be deleted or kept for record.

The default branch is reserved for the canonical, agency-wide artefacts: the translation memory itself, the cross-client glossaries, and the agency's style guides. Changes there happen rarely, and they happen through deliberate, head-of-localisation-led merges, often as a separate housekeeping task that is not driven by the AI at all. Direct pushes to the default branch are still forbidden through branch protection, and the few merges that do happen still go through human approval. But the bulk of the AI's output never touches the default branch.

This shifts how branch protection is configured. The default branch still requires a pull request and at least one approval from the head of localisation before merging, and required status checks still include the format validation and a TM consistency check. But the agency does not pressure linguists to merge AI feature branches. The expected lifecycle of an AI branch is: produced by the worker, reviewed by a linguist, the translation is exported into the client deliverable, the branch is closed.

The GitHub Personal Access Token used by the worker follows exactly the same rules as in the software scenario. It is a fine-grained token, scoped to this single repository, with Read and write permissions on Contents and Pull requests, Read-only on Metadata, and no Administration permission.

Setting up the Jira board

The Jira project mirrors the engagement portfolio. Each issue represents a unit of translation work, such as a software string batch, a marketing campaign, a contract addendum, or a chapter of a book.

The board has four columns that match the ShipifyAI model. The source column, named "Ready for AI drafting", holds tasks that have been screened by a project manager and are deemed appropriate for AI drafting. The In Progress column holds tasks the AI is currently working on. The In Review column, renamed "Ready for linguist review", holds tasks where the AI has produced a draft on a feature branch and a pull request has been opened. From this column a senior translator picks up the draft. The Incomplete column holds tasks the AI returned because the brief was insufficient or because the content required a linguist's judgement before drafting could begin.

The board has a fifth column, "Backlog", which is not visible to the AI. The intake project manager lands every new task there. The head of localisation or the lead linguist on a given client reviews each task, decides whether it is appropriate for AI drafting, and only then moves it to "Ready for AI drafting". This intake step is the agency's primary safety gate. Anything under strict NDA, anything literary where the author's voice must come through a single human translator, and anything legally binding is never moved to the AI column. It stays with a human linguist throughout.

The minimum wait time on the project is set to a few hours rather than a full business day. Translation deadlines are often tight, but the buffer still gives a senior translator a window to claim a task they want to handle themselves. This preserves skill development on the junior side and gives clients the option to request a named lead translator without losing time.

Setting up the Slack channel

The agency uses Slack for internal coordination. A dedicated channel, `#localisation-ai`, is configured as the project's notification channel in ShipifyAI. The channel is restricted to linguists and project managers. Notifications it receives include the announcement that a draft is ready for review, with a link to the pull request that holds it, and the announcement that the AI was unable to complete a task and the reason why. The link in the notification is the linguist's entry point: they click through, read the diff, and take the work from there. The channel is a recap of the AI's activity, not a substitute for the agency's main coordination channel.

The Slack Bot Token is generated and configured exactly as described in the worker configuration article, with the same four scopes. The bot is invited explicitly to `#localisation-ai` and to no other channel. In particular it is never invited to any channel shared with a client.

Writing a CLAUDE.md for the translation context

The `CLAUDE.md` file is where the agency's conventions are taught to the AI. It is the most important file in the repository for the quality of the drafts produced, and it is worth investing time in.

The file opens with a project overview that explains the agency's language pairs, its principal domains, and the way work is organised by client. The AI then knows that "the client" refers to a specific engagement with its own conventions, and that the source-language file is always the truth of record while the target file is the working artefact.

The file describes the structure of the repository, naming the per-client directories, the shared TM, and the shared glossaries. It tells the AI that TM and glossary updates propagate to active work only through the deliberate action of a linguist pulling in the latest version, so a TM edit must never silently rewrite an in-flight target.

The file describes the agency's house rules for translation. This includes target-locale formality registers per client, brand-voice notes, do-not-translate lists, and placeholder handling rules. The file explains how to treat ICU message format, how to keep HTML and Markdown markup intact, how to localise units, dates, currencies, and addresses per target locale, and how to apply inclusive-language and gender rules per target language. The file lists which segment-length constraints apply to UI strings and how to flag a segment for human attention when the source is ambiguous.

The file also lists what the AI must never do. It must never invent terminology that is not in the client glossary or the TM. It must never silently change a placeholder, a tag, or a code block. It must never produce a translation in a tone outside the client's approved register. It must never include text from one client's TM in another client's deliverable. It must never bypass the review gate by trying to push directly to the default branch.

The file ends with a checks section. Before considering a task complete the AI must run the agency's lint script, which validates format integrity and placeholder preservation. It must run the TM consistency check and flag any segment that diverges from the established translation of the same source segment. It must produce a summary of the change in the pull request body, written for the reviewing linguist, listing every segment that needed special attention.

Allowed MCP servers for translation

This is where the translation scenario diverges most clearly from the software scenario. The AI needs structured access to the agency's translation memory, the client's glossary, and the client's style guide, and it must not be allowed to leak source material to public machine translation services. MCP servers are the right tool because they expose a typed interface that the AI can call by name, and the agency controls which servers are connected and what they expose.

The agency enables a small, curated set of MCP servers on the worker machine, configured in `~/.claude/mcp.json`. The list is intentionally narrow.

• A translation-memory MCP server, scoped to the agency's own TM in the `tm` directory of the repository. The server exposes fuzzy match search by source segment, exact match search, and concordance search across the TM.
• A glossary MCP server, scoped to the client glossary for the current engagement and the shared glossaries at the root. The server exposes lookup by source term, by target term, and by domain.
• A style-guide MCP server, scoped to the client's `style-guide.md`. The server exposes structured lookups for register, tone, and conventions.
• A reference-corpus MCP server, scoped to past published translations the client has approved. The server exposes search so the AI can model the client's voice from real examples.
• A filesystem MCP server, scoped to the working directory of the repository. This is the same MCP recommended in the software scenario.

The agency explicitly does not connect MCP servers that the AI could use to bypass the confidentiality model. There is no MCP server connected to a public machine translation service. The single biggest legal risk in AI-assisted translation work is leaking client source text to a third-party MT provider, where the text may be retained or used for training. There is no MCP server that can fetch arbitrary URLs from the open internet, because that would let the AI cite an unverified translation as if it were authoritative. There is no MCP server connected to the agency's email, billing, or CRM.

The MCP configuration file lists the chosen servers under `mcpServers`, naming each one and specifying the command that runs it. Each server runs as a child process of Claude Code on the worker machine, with its own credentials managed inside the server itself, and only the typed interface is exposed to the AI.

Skills for translation drafting

The agency ships its own skill pack inside `.claude/skills`, parallel to the software scenario but tailored for translation work.

A `translate-segment` skill describes the agency's preferred approach to a single source segment: consult the TM first for an existing translation, consult the glossary for any terms involved, consult the style guide for the right register, and only then produce a target segment. The skill enforces a strict rule that any segment matching an existing TM entry above a configurable threshold must reuse that translation verbatim.

An `apply-glossary` skill describes how to apply the client glossary across a draft, including how to handle plural and possessive forms in the target language and how to mark a do-not-translate item.

A `localise-units` skill describes how to convert units, dates, currencies, addresses, and phone-number formats from the source locale to the target locale, and lists the agency's preferred conventions per target.

A `qa-consistency` skill describes the post-translation quality assurance pass, including the TM consistency check, the placeholder integrity check, the length constraint check for UI strings, and the inclusive-language check for the target locale.

A `self-review-translation` skill mirrors the software self-review skill but adapted for translation artefacts. It instructs the AI to re-read the draft as a sceptical reviewer, to check that every glossary term is honoured, to verify that no placeholders or tags are missing, to confirm that segment counts match, and to flag any segment where the source is ambiguous and a human linguist should decide.

Machine translation post-editing is a familiar pattern in this industry, and the agency's linguists should understand the difference between MTPE and the ShipifyAI workflow. In MTPE the linguist is editing raw machine output. Here the AI is a drafting assistant under linguist control: it consults the TM, the glossary, and the style guide, and produces a draft that already conforms to client conventions. The review is not a clean-up of poor MT but a confirmation that the agency's standards have been met.

Iterating with the AI through review comments

The linguist is not limited to taking the first draft as-is. The same PR review follow-up loop that the software workflow uses is available in the translation agency scenario, and it is the natural way to push corrections back to the AI segment by segment.

Every pull request opened by the worker has a title that starts with `[AI GENERATED]`. As long as that prefix is in the title, the AI will keep watching the pull request and will respond to review comments on it. A linguist who wants the AI to revise a segment writes a review comment on the relevant line, exactly as a senior translator would write feedback for a junior. The comment can ask for a different word choice, a different register, a missing glossary term, a different handling of a placeholder, or any other concrete change. The comment is the instruction.

Six hours after the comment is posted, the worker treats the thread as actionable, posts a thumbs-up reaction as an acknowledgement that work has started, and asks Claude to address the comment in the context of the current branch. If Claude makes the change it commits the edit to the same feature branch with a message starting `[AI GENERATED] address review comment`, pushes the branch, and replies on the thread with `done [AI GENERATED]`. If Claude judges the comment incorrect or out of scope, it replies with `[AI GENERATED] declining` and a one-sentence reason, and leaves the segment unchanged.

The six-hour minimum delay exists deliberately so that quick clarifications between linguists do not trigger AI responses. If a linguist leaves multiple comments at once, the AI handles each thread independently in its next iteration cycle. A thread that the linguist resolves manually is skipped by the AI entirely.

This loop is what makes the "draft on a branch, take it from there" model practical. The linguist does not need to rewrite every segment they disagree with. They can hand back specific corrections, get a revised version a few hours later, and only then decide whether to export the translation into the CAT tool or discard the branch.

Security and confidentiality

The four pillars of ShipifyAI's security model apply to the translation scenario as they do to the software scenario, with a few translation-specific reinforcements.

The worker runs on a dedicated, isolated machine with no client confidential data outside the active task. The agency runs separate workers for engagements that have heightened confidentiality obligations, so that a draft prepared for one client never sees the source files of another. The worker machine has no email client, no CAT tool credentials, and no access to the agency's billing or time-keeping systems. The AI sees only the per-client directory it is working on and the MCP servers explicitly listed in the configuration.

The AI does not modify Jira directly. The project manager's intake decisions are the agency's primary safety gate, and the worker only ever sees tasks that have been approved into the source column.

The AI cannot push to the default branch. The AI's working artefact is always a feature branch with a pull request, and the linguist takes the translation from there into the client deliverable without merging in most cases. The PAT scope refuses direct pushes to the default branch, the deny list in the Claude settings refuses it, the CLI's branching logic does not produce such pushes, and the branch protection rule on the GitHub side would reject the operation.

In addition to the standard four pillars, the agency enables an egress firewall on the worker machine that allows outbound traffic only to the GitHub API, the ShipifyAI backend, the Anthropic API, the Slack API, and the specific endpoints of the allowed MCP servers. The AI cannot reach the open internet from the worker, so it cannot exfiltrate source text to public MT services and it cannot fetch arbitrary URLs that pretend to be reference translations. The agency also enables read-only mounts for everything outside the project working directory and rotates the worker container daily.

A typical task end-to-end

Consider how a single task flows through this setup. A client sends a 500-segment marketing campaign for localisation from EN to PL, with a four-day deadline. The project manager creates a Jira issue titled "Localise Q3 marketing campaign EN to PL", attaches the source files, references the client glossary and style guide, and lands the task in Backlog. The lead linguist for that client reviews the brief, judges it appropriate for AI drafting, and moves it to "Ready for AI drafting". The minimum wait time of a few hours ticks down.

The next morning the worker picks up the task. Claude reads `CLAUDE.md`, loads the translation skills, retrieves matching segments from the agency's TM, looks up every relevant term in the client glossary, consults the style guide for the campaign register, and produces a feature branch with the translated XLIFF. Each segment that matched the TM above the threshold reuses the existing translation verbatim. Each new segment is annotated with a comment when the source is ambiguous. The AI then runs the lint script, runs the qa-consistency skill, runs the self-review-translation skill, and opens a pull request titled "[AI GENERATED] Localise Q3 marketing campaign EN to PL". The pull request body summarises the work, lists the TM hit rate, and flags the segments that need linguist attention. The Slack bot posts the link to `#localisation-ai` and the Jira task moves to "Ready for linguist review".

A senior translator opens the pull request, reads the diff segment by segment alongside the glossary, accepts most of the AI's choices, asks for a softer tone on three segments via review comments, and rejects one suggested rendering with a counter-proposal. Six hours later the worker addresses each thread independently, makes the changes, replies `done [AI GENERATED]` on each, and pushes the revised segments to the same branch. The translator reads the revisions, accepts them, exports the final XLIFF into the client's translation management system, and the pull request is closed without merging.

The Jira task moves to Done the moment the translator has exported the file. The Slack channel announces the pickup. Nothing on the default branch needed to change for the campaign to be delivered.

At every step a human controls the gate. The lead linguist decides what the AI works on. The reviewing translator decides which segments are good enough to deliver and which need revision. The AI does the bulk of the consistency work and the segment drafting, which is exactly the kind of work that benefits from automation, while the linguistic judgement remains entirely with the linguists.

Where to go next

The worker configuration article explains how to obtain and install each integration token in detail. The Claude configuration article explains how to write `CLAUDE.md`, how to author skills, and how to configure the allowList. The control article explains how a linguist takes a draft or a task back from the AI at any point. The security article explains the four pillars in depth, including the rationale behind each layer of defence.