Translation Workflow

Translation is intentionally not an automatic black box. OpenBBQ prepares a structured worksheet; a human or Agent supplies semantic translations and can validate them incrementally.

Prerequisite

Create source cues first:

openbbq segment --workspace workspaces/demo

Create a worksheet

Use a BCP-47-style target language code such as zh, ja, or pt-BR:

openbbq translate init zh --workspace workspaces/demo

This creates translation.zh.json. Each item is tied to a cue id and includes source text, timing, target budget, glossary hints, and target: null.

If a worksheet already exists, init refuses to overwrite it. Regenerate only when you accept losing all filled targets:

openbbq translate init zh --workspace workspaces/demo --force

Fill targets directly

Edit translation.zh.json while preserving its schema and cue ids. Change only the semantic target fields unless you understand the integrity checks:

{
  "id": 1,
  "source": "Tools should expose the process.",
  "target": "工具应该让过程透明。"
}

Apply translations in batches

For long videos, use small {id: text} files that are easy to review and retry:

{
  "1": "第一句译文",
  "2": "第二句译文"
}

openbbq translate apply zh batch-01.json --workspace workspaces/demo
openbbq translate apply zh batch-02.json --workspace workspaces/demo

Applying a batch is repeatable. Existing ids are overwritten and reported; unknown or malformed ids are rejected instead of silently corrupting the worksheet.

Validate completeness and quality signals

openbbq translate check zh --workspace workspaces/demo

If only one worksheet exists, omit the language:

openbbq translate check --workspace workspaces/demo

The report includes:

• Filled and total cue counts.
• Missing cue ids.
• Targets that exceed the generated character budget.
• Glossary term warnings.
• Worksheet/cue integrity problems.

Over-budget and terminology results are review signals. Completeness is required for target or bilingual export unless --allow-missing is used.

Multiple target languages

Each language has an independent worksheet:

openbbq translate init zh --workspace workspaces/demo
openbbq translate init ja --workspace workspaces/demo

Export the desired language explicitly with --to.

Using a glossary

A glossary bound in manifest.json is included automatically. Override it for one worksheet:

openbbq translate init zh --workspace workspaces/demo --glossary project-name

See Glossaries for schema and lifecycle details.