opencode-translate 0.1.2 → 0.2.0

package/README.md

@@ -1,15 +1,15 @@
 # opencode-translate
 
-`opencode-translate` is an OpenCode plugin that lets the user chat in a configured `sourceLanguage` while the main chat loop and compaction summariser only see English.
+`opencode-translate` is an OpenCode plugin that lets the user chat in a configured `lang` while the main chat loop and compaction summariser only see English.
 
 ## What It Does
 
 - Activates once per root session when any root-session user message contains a trigger keyword such as `$en`.
-- Translates user-authored text parts from `sourceLanguage` to English before the main LLM sees them.
+- Translates user-authored text parts from `lang` to English before the main LLM sees them.
 - Stores the original user text, plus a cached English translation in part metadata.
 - Shows a visible `→ EN: ...` preview under each translated user text part.
-- Translates assistant text parts from English into `displayLanguage` when each text part completes.
-- Translates the built-in `question` tool's question text, header, and every option's label and description into `displayLanguage` so the TUI confirmation dialog is in the user's language. The tool output string returned to the LLM is restored to English, including translation of non-empty custom answers.
+- Translates assistant text parts from English into `lang` when each text part completes.
+- Translates the built-in `question` tool's question text, header, and every option's label and description into `lang` so the TUI confirmation dialog is in the user's language. The tool output string returned to the LLM is restored to English, including translation of non-empty custom answers.
 - Stores assistant text as:
 
 ```md
@@ -18,7 +18,7 @@
 <!-- oc-translate:{nonce}:start -->
 ---
 
-**{displayLanguageLabel}:**
+**Translation ({lang}):**
 
 <translated>
 <!-- oc-translate:{nonce}:end -->
@@ -29,7 +29,7 @@
 ## v1 Limits
 
 - No mid-session toggle off.
-- No auto-detection of source or display language.
+- No auto-detection of the user's language. `lang` is required.
 - No title translation or title-path English enforcement.
 - No subagent translation.
 - No translation of tool inputs, tool outputs, or reasoning parts.
@@ -60,8 +60,7 @@ Add it to `~/.config/opencode/opencode.json`:
     ["opencode-translate", {
       "translatorModel": "anthropic/claude-haiku-4-5",
       "triggerKeywords": ["$en"],
-      "sourceLanguage": "ko",
-      "displayLanguage": "ko",
+      "lang": "Korean",
       "verbose": false
     }]
   ]
@@ -87,11 +86,12 @@ $en 프로젝트 루트의 package.json을 읽고 요약해줘
 | --- | --- | --- |
 | `translatorModel` | string | `anthropic/claude-haiku-4-5` |
 | `triggerKeywords` | string[] | `[$en]` |
-| `sourceLanguage` | string | `en` |
-| `displayLanguage` | string | `en` |
+| `lang` | string | Required |
 | `apiKey` | string | `undefined` |
 | `verbose` | boolean | `false` |
 
+Set `lang` to the full name of the language the user reads and writes, such as `"Korean"`, `"Japanese"`, or `"Brazilian Portuguese"`. The value is injected directly into translation prompts, so language code mapping is not required.
+
 ## Privacy
 
 Using this plugin means text goes to two model providers per turn:
@@ -133,7 +133,7 @@ If you prefer a plain API key, set `OPENAI_API_KEY` in the environment or pass `
 
 ## Manual Smoke Test
 
-1. Install the plugin and configure `sourceLanguage: "ko"`, `displayLanguage: "ko"`.
+1. Install the plugin and configure `lang: "Korean"`.
 2. Start a new session and send `$en 프로젝트 루트의 package.json을 읽고 요약해줘`.
 3. Confirm the activation banner appears.
 4. Confirm the `→ EN: ...` preview appears under the user message.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-translate",
-  "version": "0.1.2",
-  "description": "OpenCode plugin that lets the user chat in a configured source language while the main chat loop only sees English.",
+  "version": "0.2.0",
+  "description": "OpenCode plugin that lets the user chat in a configured language while the main chat loop only sees English.",
   "type": "module",
   "main": "src/index.ts",
   "license": "MIT",
@@ -34,9 +34,11 @@
     "format:check": "biome format .",
     "lint": "biome lint --write .",
     "lint:check": "biome lint .",
+    "knip": "knip",
     "check": "biome check --write .",
     "check:ci": "biome check .",
-    "test": "bun test"
+    "test": "bun test",
+    "test:coverage": "bun test --coverage"
   },
   "peerDependencies": {
     "@opencode-ai/plugin": ">=1.14.0"
@@ -55,6 +57,7 @@
     "@opencode-ai/plugin": "^1.14.21",
     "@types/node": "^25.6.0",
     "@typescript/native-preview": "beta",
-    "bun-types": "^1.3.13"
+    "bun-types": "^1.3.13",
+    "knip": "^6.14.1"
   }
 }

package/src/activation/chat-message.ts

@@ -0,0 +1,164 @@
+import type { Hooks } from "@opencode-ai/plugin"
+import {
+  buildInboundTranslationError,
+  isUserAuthoredTextPart,
+  LLM_LANGUAGE,
+  NONCE_PATTERN,
+  normalizeReason,
+  type TextPartLike,
+  type TranslateState,
+} from "../constants"
+import { hashText } from "../translator"
+import { logError } from "./logging"
+import { mergeTranslatedMetadata } from "./metadata"
+import { createActivationBannerPart, createActivationBannerText, createLlmOnlyTextPart } from "./parts"
+import { cacheSessionState, createState, resolveSessionState } from "./state"
+import { findTriggerMatch, stripTriggerKeyword } from "./trigger"
+import { type HookContext, INACTIVE_ROOT_SESSION, type ResolvedSessionState } from "./types"
+
+type ChatMessageHook = NonNullable<Hooks["chat.message"]>
+type ChatMessageInput = Parameters<ChatMessageHook>[0]
+type ChatMessageOutput = Parameters<ChatMessageHook>[1]
+
+interface ActivationResult {
+  state?: TranslateState
+  activatedThisTurn: boolean
+  aborted: boolean
+}
+
+interface PartProcessingResult {
+  nextParts: TextPartLike[]
+  eligibleIndex: number
+  errors: { part: TextPartLike; error: unknown }[]
+  firstUserTextPart?: TextPartLike & { text: string }
+}
+
+async function activateFromTrigger(
+  ctx: HookContext,
+  input: ChatMessageInput,
+  output: ChatMessageOutput,
+  resolved: ResolvedSessionState,
+): Promise<ActivationResult> {
+  if (resolved.state || !resolved.canActivate)
+    return { state: resolved.state, activatedThisTurn: false, aborted: false }
+
+  const match = findTriggerMatch(output.parts as TextPartLike[], ctx.options.triggerKeywords)
+  if (!match) return { activatedThisTurn: false, aborted: false }
+
+  const part = output.parts[match.partArrayIndex] as TextPartLike & { text: string }
+  const originalText = part.text
+  part.text = stripTriggerKeyword(part.text, match.keyword, match.offset)
+  const state = createState(ctx.options)
+  if (!NONCE_PATTERN.test(state.translate_nonce)) {
+    part.text = originalText
+    await logError(ctx.client, new Error("Generated invalid translation nonce"))
+    return { activatedThisTurn: false, aborted: true }
+  }
+
+  cacheSessionState(input.sessionID, state)
+  return { state, activatedThisTurn: true, aborted: false }
+}
+
+async function translateUserPart(
+  ctx: HookContext,
+  state: TranslateState,
+  part: TextPartLike & { text: string },
+  eligibleIndex: number,
+  nextParts: TextPartLike[],
+  errors: { part: TextPartLike; error: unknown }[],
+) {
+  try {
+    const english = await ctx.translator.translateText({
+      text: part.text,
+      sourceLanguage: state.translate_user_lang,
+      targetLanguage: LLM_LANGUAGE,
+      direction: "inbound",
+    })
+    const sourceHash = hashText(part.text)
+    part.metadata = { ...(part.metadata ?? {}), ...mergeTranslatedMetadata(state, part, english) }
+    part.text = `${part.text}\n\n_→ EN: ${english}_`
+    nextParts.push(
+      createLlmOnlyTextPart(part.sessionID, part.messageID, english, {
+        translate_role: "llm_only_translation",
+        translate_nonce: state.translate_nonce,
+        translate_source_hash: sourceHash,
+        translate_part_index: eligibleIndex,
+      }),
+    )
+  } catch (error) {
+    errors.push({ part, error })
+    const reason = normalizeReason(error)
+    await logError(ctx.client, buildInboundTranslationError(state.translate_user_lang, reason))
+    const originalText = part.text
+    part.text = `${originalText}\n\n_⚠️ Translation failed: ${reason}. Original text was sent to the model._`
+    part.ignored = true
+    nextParts.push(
+      createLlmOnlyTextPart(part.sessionID, part.messageID, originalText, {
+        translate_role: "llm_only_fallback",
+        translate_nonce: state.translate_nonce,
+        translate_part_index: eligibleIndex,
+      }),
+    )
+  }
+}
+
+async function processParts(
+  ctx: HookContext,
+  output: ChatMessageOutput,
+  state: TranslateState,
+): Promise<PartProcessingResult> {
+  const result: PartProcessingResult = { nextParts: [], eligibleIndex: 0, errors: [] }
+  for (const part of output.parts as TextPartLike[]) {
+    result.nextParts.push(part)
+    if (!isUserAuthoredTextPart(part)) continue
+    result.firstUserTextPart ??= part
+    const currentEligibleIndex = result.eligibleIndex
+    result.eligibleIndex += 1
+    if (part.text.trim().length === 0) continue
+    await translateUserPart(ctx, state, part, currentEligibleIndex, result.nextParts, result.errors)
+  }
+  return result
+}
+
+function appendActivationBanner(
+  ctx: HookContext,
+  input: ChatMessageInput,
+  output: ChatMessageOutput,
+  state: TranslateState,
+  processed: PartProcessingResult,
+) {
+  const bannerText = createActivationBannerText(ctx.options)
+  if (processed.firstUserTextPart !== undefined) {
+    processed.firstUserTextPart.text = `${processed.firstUserTextPart.text}\n\n_${bannerText}_`
+  }
+  processed.nextParts.push(createActivationBannerPart(input.sessionID, output.message.id, state, bannerText))
+}
+
+async function handleChatMessage(ctx: HookContext, input: ChatMessageInput, output: ChatMessageOutput) {
+  const resolved = await resolveSessionState(ctx.client, ctx.directory, input.sessionID)
+  const activation = await activateFromTrigger(ctx, input, output, resolved)
+  if (activation.aborted || !activation.state) return
+
+  const processed = await processParts(ctx, output, activation.state)
+  if (
+    activation.activatedThisTurn &&
+    processed.errors.length > 0 &&
+    processed.eligibleIndex === processed.errors.length
+  ) {
+    cacheSessionState(input.sessionID, INACTIVE_ROOT_SESSION)
+    return
+  }
+
+  if (activation.activatedThisTurn) appendActivationBanner(ctx, input, output, activation.state, processed)
+  output.parts.splice(0, output.parts.length, ...(processed.nextParts as typeof output.parts))
+}
+
+export function createChatMessageHook(ctx: HookContext): ChatMessageHook {
+  return async (input, output) => {
+    try {
+      await handleChatMessage(ctx, input, output)
+    } catch (error) {
+      await logError(ctx.client, error)
+    }
+  }
+}

package/src/activation/index.ts

@@ -0,0 +1,38 @@
+import type { Hooks, PluginInput, PluginOptions } from "@opencode-ai/plugin"
+import { type PluginClientLike, resolveOptions } from "../constants"
+import { createTranslator } from "../translator"
+import { createChatMessageHook } from "./chat-message"
+import { createMessagesTransformHook } from "./messages-transform"
+import { createToolExecuteAfterHook, createToolExecuteBeforeHook, resetQuestionSnapshots } from "./question-hooks"
+import { resetSessionStateCache } from "./state"
+import { createTextCompleteHook } from "./text-complete"
+import type { HookContext, HookDependencies } from "./types"
+
+export { extractStoredState } from "./state"
+export { findTriggerMatch, stripTriggerKeyword } from "./trigger"
+
+export function __resetActivationCacheForTest() {
+  resetSessionStateCache()
+  resetQuestionSnapshots()
+}
+
+export function createHooks(ctx: PluginInput, rawOptions: PluginOptions = {}, deps: HookDependencies = {}): Hooks {
+  if (process.env.OPENCODE_TRANSLATE_DISABLE === "1") return {}
+
+  const client = ctx.client as unknown as PluginClientLike
+  const options = resolveOptions(rawOptions)
+  const hookContext: HookContext = {
+    client,
+    directory: ctx.directory,
+    options,
+    translator: deps.translator ?? createTranslator(client, options),
+  }
+
+  return {
+    "chat.message": createChatMessageHook(hookContext),
+    "experimental.chat.messages.transform": createMessagesTransformHook(hookContext),
+    "experimental.text.complete": createTextCompleteHook(hookContext),
+    "tool.execute.before": createToolExecuteBeforeHook(hookContext),
+    "tool.execute.after": createToolExecuteAfterHook(hookContext),
+  }
+}

package/src/activation/logging.ts

@@ -0,0 +1,11 @@
+import { normalizeReason, PLUGIN_NAME, type PluginClientLike } from "../constants"
+
+export function logError(client: PluginClientLike, error: unknown) {
+  return client.app.log({
+    body: {
+      service: PLUGIN_NAME,
+      level: "error",
+      message: normalizeReason(error),
+    },
+  })
+}

package/src/activation/messages-transform.ts

@@ -0,0 +1,38 @@
+import type { Hooks } from "@opencode-ai/plugin"
+import { isTextPart, type MessageWithPartsLike } from "../constants"
+import { extractEnglishHistoryText } from "../formatting"
+import { logError } from "./logging"
+import { isTranslatedUserDisplayPart } from "./metadata"
+import { resolveSessionState } from "./state"
+import type { HookContext } from "./types"
+
+type MessagesTransformHook = NonNullable<Hooks["experimental.chat.messages.transform"]>
+
+export function createMessagesTransformHook(ctx: HookContext): MessagesTransformHook {
+  return async (_input, output) => {
+    try {
+      const sessionID = output.messages[0]?.info.sessionID
+      if (!sessionID) return
+
+      const resolved = await resolveSessionState(ctx.client, ctx.directory, sessionID)
+      const activeState = resolved.state
+      if (!activeState) return
+
+      for (const message of output.messages as MessageWithPartsLike[]) {
+        if (message.info.role === "user") {
+          for (const part of message.parts) {
+            if (isTranslatedUserDisplayPart(part)) part.ignored = true
+          }
+          continue
+        }
+
+        if (message.info.role !== "assistant") continue
+        for (const part of message.parts) {
+          if (isTextPart(part)) part.text = extractEnglishHistoryText(part.text, activeState.translate_nonce)
+        }
+      }
+    } catch (error) {
+      await logError(ctx.client, error)
+    }
+  }
+}

package/src/activation/metadata.ts

@@ -0,0 +1,41 @@
+import {
+  isTextPart,
+  isTranslateStateRecord,
+  LLM_LANGUAGE,
+  type StoredTextMetadata,
+  type TextPartLike,
+  type TranslateState,
+} from "../constants"
+import { hashText } from "../translator"
+
+export function asMetadata(part: TextPartLike): StoredTextMetadata {
+  return (part.metadata ?? {}) as StoredTextMetadata
+}
+
+export function extractStateFromMetadata(metadata: StoredTextMetadata | undefined): TranslateState | undefined {
+  if (!isTranslateStateRecord(metadata)) return undefined
+  return {
+    translate_enabled: true,
+    translate_user_lang: metadata.translate_user_lang,
+    translate_llm_lang: LLM_LANGUAGE,
+    translate_nonce: metadata.translate_nonce,
+  }
+}
+
+export function mergeTranslatedMetadata(
+  state: TranslateState,
+  part: TextPartLike,
+  english: string,
+): Record<string, unknown> {
+  return {
+    ...(part.metadata ?? {}),
+    ...state,
+    translate_source_hash: hashText(part.text ?? ""),
+    translate_en: english,
+  }
+}
+
+export function isTranslatedUserDisplayPart(part: TextPartLike): boolean {
+  if (!isTextPart(part) || part.synthetic === true) return false
+  return extractStateFromMetadata(asMetadata(part)) !== undefined
+}

package/src/activation/parts.ts

@@ -0,0 +1,53 @@
+import {
+  parseTranslatorModel,
+  type ResolvedTranslateOptions,
+  SPEC_VERSION,
+  type TextPartLike,
+  type TranslateState,
+} from "../constants"
+import { createSyntheticPartID } from "../translator"
+
+export function createActivationBannerText(options: ResolvedTranslateOptions): string {
+  const { modelID } = parseTranslatorModel(options.translatorModel)
+  return `✓ Translation mode enabled · translator: ${modelID} · language: ${options.lang}`
+}
+
+export function createLlmOnlyTextPart(
+  sessionID: string,
+  messageID: string,
+  text: string,
+  metadata: Record<string, unknown>,
+): TextPartLike {
+  return {
+    id: createSyntheticPartID(),
+    sessionID,
+    messageID,
+    type: "text",
+    text,
+    synthetic: true,
+    ignored: false,
+    metadata,
+  }
+}
+
+export function createActivationBannerPart(
+  sessionID: string,
+  messageID: string,
+  state: TranslateState,
+  text: string,
+): TextPartLike {
+  return {
+    id: createSyntheticPartID(),
+    sessionID,
+    messageID,
+    type: "text",
+    text,
+    synthetic: true,
+    ignored: true,
+    metadata: {
+      ...state,
+      translate_role: "activation_banner",
+      translate_spec_version: SPEC_VERSION,
+    },
+  }
+}

package/src/activation/question-hooks.ts

@@ -0,0 +1,95 @@
+import type { Hooks } from "@opencode-ai/plugin"
+import { buildInboundTranslationError, LLM_LANGUAGE, normalizeReason } from "../constants"
+import {
+  isQuestionArgs,
+  type QuestionSnapshot,
+  type QuestionToolOutput,
+  restoreQuestionOutput,
+  snapshotQuestions,
+  translateQuestionArgs,
+} from "../question-tool"
+import { logError } from "./logging"
+import { resolveSessionState } from "./state"
+import { type HookContext, QUESTION_TOOL_ID } from "./types"
+
+const questionSnapshots = new Map<string, QuestionSnapshot>()
+
+export function resetQuestionSnapshots() {
+  questionSnapshots.clear()
+}
+
+export function createToolExecuteBeforeHook(ctx: HookContext): NonNullable<Hooks["tool.execute.before"]> {
+  return async (input, output) => {
+    try {
+      if (input.tool !== QUESTION_TOOL_ID) return
+      const resolved = await resolveSessionState(ctx.client, ctx.directory, input.sessionID)
+      const activeState = resolved.state
+      if (!activeState) return
+
+      const args = output.args as unknown
+      if (!isQuestionArgs(args)) return
+
+      const original = snapshotQuestions(args)
+      if (activeState.translate_user_lang !== LLM_LANGUAGE) {
+        try {
+          await translateQuestionArgs(args, (text) =>
+            ctx.translator.translateText({
+              text,
+              sourceLanguage: LLM_LANGUAGE,
+              targetLanguage: activeState.translate_user_lang,
+              direction: "outbound",
+            }),
+          )
+        } catch (error) {
+          args.questions.splice(0, args.questions.length, ...snapshotQuestions({ questions: original }))
+          await logError(ctx.client, error)
+          return
+        }
+      }
+
+      questionSnapshots.set(input.callID, { original, translated: snapshotQuestions(args) })
+    } catch (error) {
+      await logError(ctx.client, error)
+    }
+  }
+}
+
+export function createToolExecuteAfterHook(ctx: HookContext): NonNullable<Hooks["tool.execute.after"]> {
+  return async (input, output) => {
+    try {
+      if (input.tool !== QUESTION_TOOL_ID) return
+      const snapshot = questionSnapshots.get(input.callID)
+      if (!snapshot) return
+      questionSnapshots.delete(input.callID)
+
+      const resolved = await resolveSessionState(ctx.client, ctx.directory, input.sessionID)
+      const activeState = resolved.state
+      const translateCustomAnswer =
+        activeState && activeState.translate_user_lang !== LLM_LANGUAGE
+          ? (text: string) =>
+              ctx.translator.translateText({
+                text,
+                sourceLanguage: activeState.translate_user_lang,
+                targetLanguage: LLM_LANGUAGE,
+                direction: "inbound",
+              })
+          : undefined
+
+      await restoreQuestionOutput(output as QuestionToolOutput, snapshot, {
+        ...(translateCustomAnswer ? { translateCustomAnswer } : {}),
+        onTranslationError: async (error) => {
+          if (!activeState) {
+            await logError(ctx.client, error)
+            return
+          }
+          await logError(
+            ctx.client,
+            buildInboundTranslationError(activeState.translate_user_lang, normalizeReason(error)),
+          )
+        },
+      })
+    } catch (error) {
+      await logError(ctx.client, error)
+    }
+  }
+}

package/src/activation/state.ts

@@ -0,0 +1,97 @@
+import { randomBytes } from "node:crypto"
+import {
+  isTextPart,
+  LLM_LANGUAGE,
+  type MessageWithPartsLike,
+  type PluginClientLike,
+  type ResolvedTranslateOptions,
+  type TranslateState,
+  unwrapData,
+} from "../constants"
+import { asMetadata, extractStateFromMetadata } from "./metadata"
+import {
+  type CachedSessionState,
+  INACTIVE_CHILD_SESSION,
+  INACTIVE_ROOT_SESSION,
+  type ResolvedSessionState,
+} from "./types"
+
+const sessionStateCache = new Map<string, CachedSessionState>()
+
+export function resetSessionStateCache() {
+  sessionStateCache.clear()
+}
+
+export function cacheSessionState(sessionID: string, state: CachedSessionState) {
+  sessionStateCache.set(sessionID, state)
+}
+
+export function createState(options: ResolvedTranslateOptions): TranslateState {
+  return {
+    translate_enabled: true,
+    translate_user_lang: options.lang,
+    translate_llm_lang: LLM_LANGUAGE,
+    translate_nonce: randomBytes(16).toString("hex"),
+  }
+}
+
+export function extractStoredState(messages: MessageWithPartsLike[]): TranslateState | undefined {
+  let fallback: TranslateState | undefined
+
+  for (const message of messages) {
+    for (const part of message.parts) {
+      if (!isTextPart(part)) continue
+      const metadata = asMetadata(part)
+      const state = extractStateFromMetadata(metadata)
+      if (!state) continue
+      if (metadata.translate_role === "activation_banner") return state
+      if (message.info.role === "user" && part.synthetic !== true && fallback === undefined) fallback = state
+    }
+  }
+
+  return fallback
+}
+
+function cachedStateResult(cached: CachedSessionState): ResolvedSessionState {
+  if (cached === INACTIVE_ROOT_SESSION) return { sessionActive: false, canActivate: true, storedMessages: [] }
+  if (cached === INACTIVE_CHILD_SESSION) return { sessionActive: false, canActivate: false, storedMessages: [] }
+  return { sessionActive: true, canActivate: false, state: cached, storedMessages: [] }
+}
+
+export async function resolveSessionState(
+  client: PluginClientLike,
+  directory: string | undefined,
+  sessionID: string,
+): Promise<ResolvedSessionState> {
+  const cached = sessionStateCache.get(sessionID)
+  if (cached !== undefined) return cachedStateResult(cached)
+
+  const session = unwrapData(
+    await client.session.get({
+      path: { id: sessionID },
+      query: { ...(directory ? { directory } : {}) },
+      throwOnError: true,
+    }),
+  )
+  if (session.parentID != null) {
+    sessionStateCache.set(sessionID, INACTIVE_CHILD_SESSION)
+    return { sessionActive: false, canActivate: false, storedMessages: [] }
+  }
+
+  const storedMessages = unwrapData(
+    await client.session.messages({
+      path: { id: sessionID },
+      query: { ...(directory ? { directory } : {}) },
+      throwOnError: true,
+    }),
+  )
+  const state = extractStoredState(storedMessages)
+  sessionStateCache.set(sessionID, state ?? INACTIVE_ROOT_SESSION)
+
+  return {
+    sessionActive: Boolean(state),
+    canActivate: !state,
+    state: state ?? undefined,
+    storedMessages,
+  }
+}