update_translations

Update or overwrite existing translations for a specific language in POEditor translation projects. Provide term, context, and content to modify multilingual content.

Instructions

Update/overwrite translations for a language. Important: if a term was created with a context, you must provide the same context value to match that term.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`project_id`	No
`language`	Yes
`items`	Yes

Implementation Reference

src/server.ts:173-182 (handler)

The asynchronous handler function that implements the core logic of the 'update_translations' tool. It constructs a payload from the input items, calls the POEditor 'translations/update' API endpoint via the poeditor helper, and returns the result.

async (args) => {
  const id = requireProjectId(args.project_id ?? null);
  const payload = args.items.map((i) => ({
    term: i.term,
    context: i.context ?? "",
    translation: i.plural ? { plural: i.plural } : { content: i.content, fuzzy: i.fuzzy ? 1 : 0 }
  }));
  const data = JSON.stringify(payload);
  const res = await poeditor("translations/update", { id: String(id), language: args.language, data });
  return { content: [{ type: "text", text: JSON.stringify(res.result ?? {}, null, 2) }] };

src/server.ts:47-62 (schema)

Zod schema (TranslationsInput) that validates the input parameters for the 'update_translations' tool, including optional project_id, required language, and array of translation items with term, context, content, fuzzy flag, and optional plurals.

const TranslationsInput = z.object({
  project_id: z.number().int().positive().optional(),
  language: z.string().min(2),
  items: z.array(z.object({
    term: z.string().min(1),
    context: z.string().optional(),
    content: z.string().default(""),
    fuzzy: z.boolean().optional(),
    plural: z.object({
      one: z.string().optional(),
      few: z.string().optional(),
      many: z.string().optional(),
      other: z.string().optional()
    }).partial().optional()
  })).min(1)
});

src/server.ts:169-184 (registration)

The server.tool() call that registers the 'update_translations' tool with the MCP server, specifying its name, description, input schema, and handler function.

server.tool(
  "update_translations",
  "Update/overwrite translations for a language. Important: if a term was created with a context, you must provide the same context value to match that term.",
  TranslationsInput.shape,
  async (args) => {
    const id = requireProjectId(args.project_id ?? null);
    const payload = args.items.map((i) => ({
      term: i.term,
      context: i.context ?? "",
      translation: i.plural ? { plural: i.plural } : { content: i.content, fuzzy: i.fuzzy ? 1 : 0 }
    }));
    const data = JSON.stringify(payload);
    const res = await poeditor("translations/update", { id: String(id), language: args.language, data });
    return { content: [{ type: "text", text: JSON.stringify(res.result ?? {}, null, 2) }] };
  }
);

src/server.ts:40-44 (helper)

Helper function used by the 'update_translations' handler to resolve the project_id from arguments or environment variable.

function requireProjectId(argProjectId?: number | null) {
  const id = argProjectId ?? (PROJECT_ID ? Number(PROJECT_ID) : null);
  if (!id) throw new Error("project_id is required (either pass it to the tool or set POEDITOR_PROJECT_ID)");
  return id;
}

src/server.ts:19-38 (helper)

Core helper function that makes authenticated POST requests to the POEditor API, parses responses, and handles errors. Used by the 'update_translations' handler.

export async function poeditor(endpoint: string, form: Record<string, string>) {
  const body = new URLSearchParams({ api_token: API_TOKEN!, ...form });
  const { body: resBody } = await request(`${API_BASE}/${endpoint}`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: body.toString()
  });
  const text = await resBody.text();
  let json: any;
  try { json = JSON.parse(text); } catch (e) {
    throw new Error(`POEditor: invalid JSON response: ${text}`);
  }
  const status = json?.response?.status;
  if (status !== "success") {
    const code = json?.response?.code;
    const message = json?.response?.message || "Unknown POEditor error";
    throw new Error(`POEditor API error ${code ?? ""}: ${message}`);
  }
  return json;
}

POEditor MCP Server