AI Suggestions

Overview

The AI suggestions feature drafts a translation for you using Google Gemini. You can request a suggestion for a single cell, or run a bulk pass — across one target language or all of them at once. The result always lands as a regular draft — accept it, edit it, or revert it like any other change. You stay in control.

You’ll need a Gemini API key to use this feature.

---

Setting up your API key

1. Go to aistudio.google.com and create a free API key.
2. In the app, open Settings (gear icon in the header).
3. Paste your key into the AI provider key section (Provider: Gemini) and click Save.

The key is stored in your operating system’s keychain on signed builds (encrypted at rest). In dev builds (tauri dev), the key lives in the Tauri Store instead — unsigned binaries trigger repeated keychain prompts, so this is intentional. Either way, the key is local to this app and never written to the repository or synced anywhere.

---

Per-cell suggestions

1. Click a target cell (any non-source cell).
2. Open the details sidebar on the right if it’s collapsed.
3. Under AI translation, click Suggest.

While the request runs, the button shows Suggesting… with a spinner. When the response lands, it’s written into the cell as a draft and focus jumps to the textarea with the caret at the end — ready for you to tweak or commit.

The Suggest button is disabled in two situations:

• No API key configured — the section shows an “Add an AI key in Settings” link.
• Source cell selected — the tooltip reads “Source language. Pick a target cell to translate.”

Note

There’s no per-cell sparkle button on the table itself. Suggestions are always invoked from the details sidebar’s AI section.

---

Repo-level system prompt

Each repo can set an aiSystemPrompt in its translations config (top-level field, ≤2000 characters). The prompt is sent with every AI request originating from that repo.

Use it for what applies everywhere:

• “Brand name ‘Stape’ stays in English — never transliterate.”
• “Sentence case for headings. Keep every placeholder exactly as written.”
• “Match the playful voice of the marketing site; avoid corporate jargon.”

You configure the field through the wizard’s Edit project config flow.

---

Per-language prompts

Rules that apply to one language go in aiLanguagePrompts instead — a separate textarea per target language, under the system prompt in the same wizard screen (≤1000 characters each).

• it — “Address the reader with the formal Lei register. Never tu/tuo/tua/tuoi/tue.”
• es — “Address the reader with usted. Never tú/tu/tus.”
• de — “Sie and Ihr/Ihre. Never du or dein.”

Only the target language’s prompt is sent with a request. That is the point of the field, not a detail: a model translating into Italian while reading eleven other languages’ rules has to work out which one applies before it can follow it, and a rule that contradicts how copy usually reads in that language tends to lose that contest. Formal address is the usual casualty — informal is the house style in Spanish, Italian and Dutch marketing copy, so the model drifts back to it.

Where a language prompt and the system prompt disagree, the language prompt wins, and the request says so explicitly.

Tip

Each row shows the language it resolved to — it — Italian. If a row says the folder name isn’t a language tag (common with ua, cn, jp), map it under Show advanced on the project card. The prompt names the language it’s translating into, and it can only do that when the folder resolves.

---

Sharing prompts with your team

Register rules and terminology take a few bulk runs to get right. Nobody on the team should have to arrive at them twice, so the prompts travel through the repo:

1. Whoever tuned the prompts opens Edit project config and clicks Export to repo. That writes .translations.json at the repo root, prompts included.
2. Commit and push it like any other file.
3. Everyone else pulls, opens the same screen, and clicks Import prompts from repo.

Import replaces the system prompt and every per-language prompt with what the file holds. It is a shared baseline rather than a patch, so a language the file doesn’t mention ends up with no prompt — that is what makes everyone’s output match.

Nothing else moves: your projects, locales directories and BCP 47 mappings are left alone, and nothing is written until you press Save. If an import wasn’t what you wanted, Cancel is the undo.

Note

A .translations.json with no prompts in it is refused rather than imported — applying it would clear yours. Prompts over the character caps, or a file that isn’t valid JSON, are reported with the offending field and your prompts stay as they were.

---

Bulk AI translate

Need to draft many keys at once? Flip the filter sidebar to Bulk Actions.

1. Open the filter sidebar and switch the top toggle from Filter to Bulk Actions.
2. Choose a target language — or All languages to translate every target in one run.
3. Pick the set of rows to translate.
4. Start the run. The app calls Gemini in parallel batches with a progress indicator and lets you cancel mid-run.

Every result lands as a draft in the editor — review and accept them like any other edit.

Behind the scenes, bulk runs dispatch up to 3 batches in parallel, rotating across the selected target languages so the first few rows fill across every column before later rows do. Batch size adapts to the work in front of it — small jobs use small batches, large jobs ramp up to ~12 keys per batch — and the long ones go alone. Transient hiccups (rate limits, network blips) and Gemini-side output truncation are retried automatically; if a whole batch fails fatally, it’s split in half and each half is retried before any cell is marked as failed. The “(N retrying)” tag in the progress label tells you a transient issue is being worked on. Cells that don’t recover after all retries appear in the per-row error list at the bottom of the panel, and you can re-run them.

---

Tips

• Short, clear strings work best. Long values with heavy formatting usually need a manual pass afterwards.
• The model’s only context is the source value plus the system prompt. It doesn’t see surrounding keys or your other translations. If a key needs context — disambiguating “Order” the verb from “Order” the noun, for example — the system prompt is where to add it.
• Plurals are not batched. Each plural variant is its own per-cell call, so review each one individually.
• Always review before committing. The model is good but it’s not infallible; treat suggestions as a starting point, not the final answer.

---

Related

The same API key powers the AI Chat rail, where you can ask what changed, read the configured prompts, and have translations written into the columns you name.