translate-subtitles

Translate subtitles

Viewers read subtitles while the speaker is still talking: a line is narrow, stays on screen for two or three seconds, and is gone before the next one appears. So the product is subtitles, not prose. You write the full-sentence translation of each sentence; when it is placed on screen (captions_create), BaoCut aligns the translation of each sentence with the timing of the corresponding source sentence, then splits it by width into subtitle cues. Sentence boundaries must correspond one-to-one with the source, and the word order within a sentence should make each split segment roughly match what is being said at that moment; keep the text short enough to read in two or three seconds.

The most common way to get this wrong: translating it like a well-written essay. Merging two sentences into one, splitting one sentence into two, moving the second half forward for smoothness, turning the source's spoken language into written language, making every sentence noticeably longer than the source. Such a translation reads well on its own, but on screen it does not match the audio, and the subtitle changes before the viewer has read half of it.

It can also be used when the user explicitly wants only a subtitle file translated and there is no video; see the final section "When the user explicitly wants only a subtitle file" for how.

1. Confirm first

• Target language: use a BCP 47 tag (e.g. zh-Hans、en、ja). If the user has not said what to translate into, ask once. Take the source language from the transcript document's language.
• Which transcript: the one with kind speech among the documents listed by videos_inspect; if there are several, match the segment the user means by source asset (sourceAssetId), and ask if you cannot match it.
• Whether the transcript has been polished: if it has not been polished (typos, terminology, and punctuation are still as recognized), first polish it as described in polish-transcript and then translate. Polishing changes sentence segmentation and sentence fingerprints: polish first, write it back, then read the sentences to translate; after polishing a video that already has translations, most sentences need retranslation. Translating first and polishing afterward means doing it twice.
• Existing translation: if there is already a translation in the same target language whose sourceDocumentId points to this transcript (kind translation), edit it (the same documentId) rather than creating a second one; create a new one only when the user explicitly asks for a separate copy.

2. Read through, decide the translation approach

Read the transcript with documents_read, giving the target language as translateTo: BaoCut uses this to show "translating" on the video card and subtitle panel, and it ends when a translation in that language is written. The translationBasis it returns gives the segmented sentences. Before starting, read the whole text and decide the following, and follow them throughout the translation. They do not go into the product:

• Content summary: one or two sentences on what this video is about. Use it to judge misheard words and ambiguous references.
• Terminology: identify the terms in the source (the transcript may misspell them; watch for several misspellings of the same term), and use only one translation for each term throughout.
• Proper names: keep personal names, product names, and organization names, and keep them consistent throughout.
• The user's glossary: The translations the user explicitly names are hard requirements: use them verbatim: do not inflect, do not change spelling, do not add or remove spaces, do not translate, do not omit; when the user only says "it would be best to translate it this way," that is a preference: stay consistent, but it may yield to context. Each term has only one translation.
• The user's requirements: explicit requirements about tone, style, etc. have the highest priority, but they do not override the term translations the user explicitly names, nor do they override the product rules below.

3. Rules for sentence-by-sentence translation

• Translate each sentence once: do not merge, do not split, do not omit, do not reorder, and do not move a sentence into another paragraph. The preceding and following sentences serve only to understand the context.
• First understand the whole sentence, then translate faithfully and naturally using the word order that is idiomatic in the target language. The later alignment step will map the natural whole sentence onto the timeline; do not write stiff sentences in order to follow the clause order of the source.
• Among several equally natural renderings, choose the one whose clause orderfollows the source(the simultaneous-interpreting approach): subtitle lines are aligned to the source speech, so a translation whose unfolding order matches the source will have each segmented line match the meaning being heard at that moment. Reorder only when the target language genuinely requires it.
• Length is part of correctness, not a matter of style: a translation with the same meaning and fewer characters is better. First remove verbal fillers, redundant connectives, repeated subjects, and lead-ins; when two renderings are equally faithful, choose the shorter one.
• Length always comes after meaning. Never delete necessary meaning, negation, qualification, numbers, names, tone, or register just to be shorter: if the sentence genuinely needs to be that long, make it that long.
• Preserve every explicit causal, adversative, conditional, and consequential relation (because, but, if, so, and the like) and the content they govern, even if that makes the sentence longer. Line breaking may split a complete translation, but it cannot restore a clause that was left out.
• Give onlyonerendering per sentence: do not write alternatives separated by slashes or in parentheses. Slashes appear only in terms copied verbatim (for example, commands like /compact , whether they come from the source or from the user's glossary).
• Keep terminology consistent throughout.
• Follow the target language's own spacing conventions: do not insert spaces between characters in Chinese or Japanese; in Korean, write word by word, with particles and counters attached to the preceding word or number.
• Do not add line breaks or paragraph marks within a sentence; output only the translation itself, without notes, quotation marks, or the source text.

Compare (English to Chinese, for illustration only):

Source:So what we ended up doing, and this took us a while to figure out, was to let the model review first.

Bad:我们花了好一阵子才想明白，最后决定让模型先审一遍。(the second half was moved to the front: when the audience hears "what we ended up doing," the subtitle shows "花了好一阵子")

Good:我们最后的做法，花了好一阵子才想明白，就是让模型先审一遍。(the unfolding order follows the source, so once split into two or three lines, each line matches what is being said at that moment)

Additional rules when the target is Simplified Chinese

These are fixed requirements that take priority over any style you have set for yourself:

• Use idiomatic Simplified Chinese; do not copy the source word order when it reads like translationese.
• Use Chinese punctuation. Do not insert spaces between two Chinese characters, and do not insert spaces inside identifiers.
• Always put one half-width space between Chinese characters and adjacent Latin letters: Latin words, identifiers, model names, and command-line arguments including their leading hyphens. Write “35% KV cache” and “specified via --speculative-model”, not “35%KV缓存” or “通过--speculative-model指定”. Also put one space between Arabic numerals or percentages and adjacent Latin words. This is a hard requirement.
• Use “……” for ellipses, collapse runs of repeated question marks and exclamation marks into one, and do not add thousands separators to ordinary four-digit numbers.
• Preserve code, identifiers, URLs, model names, product names, and user-specified terminology verbatim: the characters of an identifier itself stay unchanged, and still add that one space when adjacent to Chinese characters.

4. Write back the video

• Following the format described in the documents_read instructions, write the complete translation with documents_put: when creating, give kind translation, language as the target language, and sourceDocument as the documentId of the transcript; when fully retranslating an existing translation, give document. When only revising a few sentences of an existing translation, use edits_apply's patchDocument and submit only the changed naturalText, sourceFingerprint, alignment, status, and other fields by the stable id of each unit (see edits_ops for the format); when updating the underlying sourceBasis, also pass only the changed fields and do not upload all units. One unit per sentence, use the translationBasis read this time as sourceBasis, and fill in each unit's alignment information (which source sentence it corresponds to, which words) as described, without omitting anything or inventing fields. Write the whole document in a single documents_put.
• Retranslate only the sentences that changed(after the transcript was edited or trimmed, or when the user says the translation is out of date): documents_read the transcript again (also passing translateTo) to get the latest translationBasis, then read the existing translation. For units whose sentence id and fingerprint both match an existing unit, keep that unit as is; retranslate those that do not match and those that are new; sentences no longer present in the transcript are not written. Replace sourceBasis with the new one. After writing back, the Runtime will swap out the changed sentences in subtitle layers built from this translation; do not build another layer. Only start over completely when the user asks for a full retranslation: retranslating unchanged sentences would only alter translations the user has already seen and edited.
• If the transcript was edited again before writing (version conflict, or what you read is no longer the current version), read it again and work from the new sentences.

5. Delivery

• Explain: the target language; how many sentences were translated (for partial retranslation, say how many were kept and how many retranslated); which terminology was followed; which sentences are uncertain and why.
• Put it on screen: create a subtitle layer with captions_create. For bilingual, give the translation document and include bilingual: true; for translation only, give the translation document. Each call with the same document adds another layer, so first use videos_inspect to check whether one has already been created.
• When the user wants subtitle files, use export (kind subtitles): for bilingual give bilingual: true(the primary document is the transcript, the secondary document is the translation, one entry per sentence); for translation only give language, and require that a subtitle layer in that language already exists on screen (captions_create first); set the line width with maxCharsPerLine. Wait for jobs_inspect to reach completed, then tell the user the path in outputs.

6. Things to avoid

• Do not merge, split, or omit sentences, and do not move the second half of a sentence to the front.
• Do not turn colloquial speech into formal written language for fluency, and do not make every sentence longer than the original.
• Do not delete negations, qualifiers, numbers, names, or causal and contrastive connectives for the sake of brevity.
• Do not provide alternative translations, do not insert line breaks within a sentence, and do not include notes or the source text.
• Do not translate before polishing; do not create a second version when a translation already exists; do not re-translate unchanged sentences in full.

7. Self-check

• Every sentence is translated, with no merged, split, omitted, or extra sentences.
• Terminology and proper nouns are consistent throughout; the wording the user specified appears verbatim in the corresponding sentences.
• Negations, numbers, qualifiers, and causal or contrastive relations are all preserved; no meaning was dropped for brevity.
• Pick a few long sentences at random and imagine splitting them into two or three lines: does each line match what is being said at that point?
• There are no alternative translations, no line breaks within a sentence, and no notes.
• Spacing and punctuation conventions of the target language are correct; for Simplified Chinese, spacing between Chinese and Western text is correct.

8. When the user explicitly asks only for a subtitle file

This is an exception: do this only when the user explicitly says they want only a subtitle file and no video or project; otherwise, translate within the video as described above.

• From a link: use transcribe with url and include noVideo: true(or use download without video, newVideo, and project, and include transcribe: true); only download and generate TXT and SRT transcripts in the download directory. For a local media file, use transcribe with file and include noVideo: true. When jobs_inspect reaches completed, outputs contains their paths; read them directly; if they cannot be read, use artifacts_save to save them to the working directory and then read them. If the user provides an existing subtitle file, read it directly.
• The target language (Section 1), reading through to decide on terminology (Section 2), and the sentence-by-sentence rules (Section 3) still apply; on this path there is no video transcript to polish, so recognition errors in the source are translated correctly according to context in the translation.
• Translate each subtitle once, preserving sequence numbers and timecodes, without merging or splitting subtitle entries.
• When one sentence spans several subtitles, understand it as a whole, then follow the rule of "follow the source order" so that each entry's translation corresponds to what is said during that entry's time.
• Write it as a new file in the working directory, with the target language tag appended to the original filename (e.g., <原名>.<目标语言>.srt), then use downloads_save to put it in the download directory and tell the user the path it returns.