fix: harden OpenAI translation requests

Author: benceruleanlu

scripts/i18n/config.ts

@@ -1,25 +1,21 @@
+import type { OpenAI } from 'openai'
+
 export interface OutputLocale {
   code: string
   name: string
   guidance?: string
 }
 
-export type ReasoningEffort =
-  | 'none'
-  | 'low'
-  | 'medium'
-  | 'high'
-  | 'xhigh'
-  | 'max'
-
 export interface TranslationPipelineConfig {
   entry: string
   output: string
   model: string
-  reasoningEffort: ReasoningEffort
+  reasoningEffort: NonNullable<
+    OpenAI.ChatCompletionCreateParams['reasoning_effort']
+  >
   maxItemsPerRequest: number
   maxSourceCharsPerRequest: number
-  localeConcurrency: number
+  stateConcurrency: number
   requestConcurrency: number
   maxTranslationRounds: number
   pruneCountFloor: number
@@ -52,7 +48,7 @@ export const translationPipelineConfig: TranslationPipelineConfig = {
   reasoningEffort: 'high',
   maxItemsPerRequest: 40,
   maxSourceCharsPerRequest: 6000,
-  localeConcurrency: 3,
+  stateConcurrency: 3,
   requestConcurrency: 2,
   maxTranslationRounds: 3,
   pruneCountFloor: 25,

scripts/i18n/translate.ts

@@ -1,10 +1,6 @@
 import OpenAI from 'openai'
 
-import type {
-  OutputLocale,
-  ReasoningEffort,
-  TranslationPipelineConfig
-} from './config'
+import type { OutputLocale, TranslationPipelineConfig } from './config'
 import { tokenErrors } from './protected-tokens'
 
 export interface TranslationItem {
@@ -58,6 +54,8 @@ export function chunkItems(
   maxItems: number,
   maxSourceChars: number
 ): TranslationItem[][] {
+  // Character count is an initial batching heuristic; truncated responses are
+  // recursively split before the translation run fails.
   const chunks: TranslationItem[][] = []
   let chunk: TranslationItem[] = []
   let chunkChars = 0
@@ -103,18 +101,29 @@ function parseBatchResponse(content: string): Record<string, string> {
     throw new Error('translation response is not a JSON object')
   }
   const record: Record<string, string> = {}
+  const invalidIds: string[] = []
   for (const [key, value] of Object.entries(parsed)) {
-    if (typeof value === 'string') record[key] = value
+    if (typeof value === 'string') {
+      record[key] = value
+    } else {
+      invalidIds.push(key)
+    }
+  }
+  if (invalidIds.length > 0) {
+    throw new Error(
+      `translation response has non-string values for ids: ${invalidIds.join(', ')}`
+    )
   }
   return record
 }
 
 interface OpenAiTranslatorOptions {
   apiKey: string
   model: string
-  reasoningEffort: ReasoningEffort
+  reasoningEffort: TranslationPipelineConfig['reasoningEffort']
   glossary: string
   fetchFn?: typeof fetch
+  onCompletion?: (completion: OpenAI.ChatCompletion) => void
   requestTimeoutMs?: number
 }
 
@@ -127,7 +136,11 @@ export function createOpenAiTranslator(
     timeout: options.requestTimeoutMs ?? defaultRequestTimeoutMs,
     maxRetries: maxNetworkRetries
   })
-  return async (locale, items) => {
+
+  async function translateBatch(
+    locale: OutputLocale,
+    items: TranslationItem[]
+  ): Promise<Record<string, string>> {
     let lastError = new Error('translation request was not attempted')
     for (let attempt = 0; attempt <= maxMalformedResponseRetries; attempt++) {
       const completion = await client.chat.completions.create({
@@ -142,12 +155,18 @@ export function createOpenAiTranslator(
           { role: 'user', content: JSON.stringify({ items }) }
         ]
       })
+      options.onCompletion?.(completion)
       const choice = completion.choices[0]
       if (choice?.finish_reason === 'length') {
-        lastError = new Error(
-          'OpenAI response was truncated (finish_reason "length"); lower maxItemsPerRequest or maxSourceCharsPerRequest'
-        )
-        continue
+        if (items.length === 1) {
+          throw new Error(
+            'OpenAI response was truncated (finish_reason "length"); lower maxItemsPerRequest or maxSourceCharsPerRequest'
+          )
+        }
+        const splitIndex = Math.ceil(items.length / 2)
+        const first = await translateBatch(locale, items.slice(0, splitIndex))
+        const second = await translateBatch(locale, items.slice(splitIndex))
+        return { ...first, ...second }
       }
       const content = choice?.message.content
       if (typeof content !== 'string') {
@@ -162,6 +181,8 @@ export function createOpenAiTranslator(
     }
     throw lastError
   }
+
+  return translateBatch
 }
 
 export async function translateLocaleItems(

scripts/i18n/update-locales.test.ts

@@ -3,6 +3,7 @@
  * (happy-dom defines window/navigator), and nothing here needs a DOM.
  * @vitest-environment node
  */
+import type { OpenAI } from 'openai'
 import { describe, expect, it, vi } from 'vitest'
 
 import type { OutputLocale } from './config'
@@ -503,20 +504,39 @@ describe('createOpenAiTranslator', () => {
       context: 'main.json: greeting',
       source: 'Hello {name}',
       preserve: ['{name}']
+    },
+    {
+      id: '2',
+      context: 'main.json: farewell',
+      source: 'Goodbye {name}',
+      preserve: ['{name}']
     }
   ]
 
-  const completion = (content: string, finishReason = 'stop') =>
+  const completion = (
+    content: string,
+    finishReason = 'stop',
+    usage?: OpenAI.CompletionUsage
+  ) =>
     new Response(
       JSON.stringify({
-        choices: [{ finish_reason: finishReason, message: { content } }]
+        choices: [{ finish_reason: finishReason, message: { content } }],
+        usage
       }),
       { status: 200, headers: { 'content-type': 'application/json' } }
     )
 
-  function translatorFor(responses: Response[]) {
+  function translatorFor(
+    responses: Response[],
+    onCompletion?: (completion: OpenAI.ChatCompletion) => void
+  ) {
     let calls = 0
-    const fetchFn: typeof fetch = async () => {
+    const requestBodies: string[] = []
+    const fetchFn: typeof fetch = async (_input, init) => {
+      if (typeof init?.body !== 'string') {
+        throw new Error('expected a JSON request body')
+      }
+      requestBodies.push(init.body)
       calls++
       return responses[calls - 1]
     }
@@ -525,20 +545,83 @@ describe('createOpenAiTranslator', () => {
       model: 'test-model',
       reasoningEffort: 'low',
       glossary: '',
-      fetchFn
+      fetchFn,
+      onCompletion
     })
-    return { translate, callCount: () => calls }
+    return { translate, callCount: () => calls, requestBodies }
   }
 
-  it('retries truncated responses instead of failing on the partial JSON', async () => {
-    const { translate, callCount } = translatorFor([
+  it('splits a truncated batch instead of retrying it unchanged', async () => {
+    const { translate, callCount, requestBodies } = translatorFor([
       completion('{"1": "Bonj', 'length'),
-      completion('{"1": "Bonjour {name}"}')
+      completion('{"1": "Bonjour {name}"}'),
+      completion('{"2": "Au revoir {name}"}')
     ])
     await expect(translate(locale, items)).resolves.toEqual({
-      '1': 'Bonjour {name}'
+      '1': 'Bonjour {name}',
+      '2': 'Au revoir {name}'
+    })
+    expect(callCount()).toBe(3)
+    expect(requestBodies[1].length).toBeLessThan(requestBodies[0].length)
+    expect(requestBodies[2].length).toBeLessThan(requestBodies[0].length)
+    expect(requestBodies[1]).toContain('main.json: greeting')
+    expect(requestBodies[1]).not.toContain('main.json: farewell')
+    expect(requestBodies[2]).not.toContain('main.json: greeting')
+    expect(requestBodies[2]).toContain('main.json: farewell')
+  })
+
+  it('does not retry a truncated single-item batch', async () => {
+    const { translate, callCount } = translatorFor([
+      completion('{"1": "Bonj', 'length')
+    ])
+    await expect(translate(locale, items.slice(0, 1))).rejects.toThrow(
+      'OpenAI response was truncated'
+    )
+    expect(callCount()).toBe(1)
+  })
+
+  it('reports non-string response values with their ids', async () => {
+    const malformed = () => completion('{"1": {"text": "Bonjour"}, "2": 42}')
+    const { translate, callCount } = translatorFor([
+      malformed(),
+      malformed(),
+      malformed(),
+      malformed()
+    ])
+    await expect(translate(locale, items)).rejects.toThrow(
+      'translation response has non-string values for ids: 1, 2'
+    )
+    expect(callCount()).toBe(4)
+  })
+
+  it('reports usage for every completed API request', async () => {
+    const totalTokens: number[] = []
+    const onCompletion = vi.fn((response: OpenAI.ChatCompletion) => {
+      if (response.usage) totalTokens.push(response.usage.total_tokens)
     })
-    expect(callCount()).toBe(2)
+    const { translate } = translatorFor(
+      [
+        completion('{"1": "Bonj', 'length', {
+          completion_tokens: 4,
+          prompt_tokens: 10,
+          total_tokens: 14
+        }),
+        completion('{"1": "Bonjour {name}"}', 'stop', {
+          completion_tokens: 5,
+          prompt_tokens: 7,
+          total_tokens: 12
+        }),
+        completion('{"2": "Au revoir {name}"}', 'stop', {
+          completion_tokens: 6,
+          prompt_tokens: 8,
+          total_tokens: 14
+        })
+      ],
+      onCompletion
+    )
+    await translate(locale, items)
+    expect(onCompletion).toHaveBeenCalledTimes(3)
+    expect(totalTokens).toEqual([14, 12, 14])
   })
 
   it('fails immediately on non-retryable statuses', async () => {

scripts/i18n/update-locales.ts

@@ -38,6 +38,7 @@ import {
 } from './protected-tokens'
 import type { TranslateBatch, TranslationItem } from './translate'
 import {
+  chunkItems,
   createOpenAiTranslator,
   mapWithConcurrency,
   translateLocaleItems
@@ -468,27 +469,62 @@ async function run(argv: readonly string[]): Promise<void> {
     (count, plan) => count + plan.items.length,
     0
   )
+  const initialBatchCount = [...translationPlans.values()].reduce(
+    (count, plan) =>
+      count +
+      chunkItems(
+        plan.items,
+        config.maxItemsPerRequest,
+        config.maxSourceCharsPerRequest
+      ).length,
+    0
+  )
+  if (pendingTotal > 0) {
+    print(
+      `Translation preflight: ${pendingTotal} strings in ${initialBatchCount} initial batches across ${config.outputLocales.length} locales; retries and truncation splits can add requests.`
+    )
+  }
 
   const apiKey = process.env.OPENAI_API_KEY
   if (pendingTotal > 0 && !apiKey) {
     throw new Error(
       `${pendingTotal} strings need translation but OPENAI_API_KEY is not set.`
     )
   }
+  const usage = {
+    completionTokens: 0,
+    promptTokens: 0,
+    reasoningTokens: 0,
+    requests: 0,
+    totalTokens: 0
+  }
+  const countedFetch: typeof fetch = async (input, init) => {
+    usage.requests++
+    return fetch(input, init)
+  }
   const translateBatch: TranslateBatch = apiKey
     ? createOpenAiTranslator({
         apiKey,
+        fetchFn: countedFetch,
         model: config.model,
         reasoningEffort: config.reasoningEffort,
-        glossary: config.glossary
+        glossary: config.glossary,
+        onCompletion: (completion) => {
+          if (!completion.usage) return
+          usage.completionTokens += completion.usage.completion_tokens
+          usage.promptTokens += completion.usage.prompt_tokens
+          usage.reasoningTokens +=
+            completion.usage.completion_tokens_details?.reasoning_tokens ?? 0
+          usage.totalTokens += completion.usage.total_tokens
+        }
       })
     : async () => {
         throw new Error('No translator available')
       }
 
   const outcomes = await mapWithConcurrency(
     states,
-    config.localeConcurrency,
+    config.stateConcurrency,
     async (
       state
     ): Promise<
@@ -602,6 +638,12 @@ async function run(argv: readonly string[]): Promise<void> {
     )
   )
 
+  if (usage.requests > 0) {
+    print(
+      `OpenAI usage: ${usage.requests} HTTP requests; ${usage.promptTokens} input, ${usage.completionTokens} output (${usage.reasoningTokens} reasoning), ${usage.totalTokens} total tokens.`
+    )
+  }
+
   if (failuresByFile.size > 0) {
     const details = [...failuresByFile.values()].flat()
     const persisted =