add_terms_with_translations

Add multiple translation terms with their corresponding translations in a single operation to POEditor projects, ensuring proper linkage between terms and translations.

Instructions

PREFERRED METHOD: Create multiple new terms and add their translations in one operation. Use this instead of calling add_terms followed by add_translations separately. This ensures terms and translations are properly linked (especially important when using context).

Input Schema

TableJSON Schema

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

Implementation Reference

src/server.ts:322-355 (handler)

The handler function for the 'add_terms_with_translations' tool. It first adds multiple terms to the POEditor project using the poeditor API, then adds translations for those terms in the specified language. It returns a combined result of terms added and translations added.

async (args) => {
  const id = requireProjectId(args.project_id ?? null);

  // Step 1: Add all terms
  const termData = JSON.stringify(args.items.map(item => ({
    term: item.term,
    context: item.context,
    reference: item.reference,
    tags: item.tags
  })));
  const termRes = await poeditor("terms/add", { id: String(id), data: termData });

  // Step 2: Add all translations
  const translationPayload = args.items.map(item => ({
    term: item.term,
    context: item.context ?? "",
    translation: item.translation.plural
      ? { plural: item.translation.plural }
      : { content: item.translation.content, fuzzy: item.translation.fuzzy ? 1 : 0 }
  }));
  const translationData = JSON.stringify(translationPayload);
  const translationRes = await poeditor("translations/add", {
    id: String(id),
    language: args.language,
    data: translationData
  });

  // Return combined result
  const result = {
    terms_added: termRes.result?.terms ?? termRes.result,
    translations_added: translationRes.result ?? {}
  };
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
}

src/server.ts:82-101 (schema)

Zod schema defining the input parameters for the add_terms_with_translations tool: optional project_id, required language code, and an array of items each with term details and translation (supporting singular, fuzzy, and plural forms).

const AddTermsWithTranslationsInput = 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(),
    reference: z.string().optional(),
    tags: z.array(z.string()).optional(),
    translation: z.object({
      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:318-356 (registration)

Registration of the 'add_terms_with_translations' tool using server.tool(), providing the tool name, description, input schema, and inline handler function.

server.tool(
  "add_terms_with_translations",
  "PREFERRED METHOD: Create multiple new terms and add their translations in one operation. Use this instead of calling add_terms followed by add_translations separately. This ensures terms and translations are properly linked (especially important when using context).",
  AddTermsWithTranslationsInput.shape,
  async (args) => {
    const id = requireProjectId(args.project_id ?? null);

    // Step 1: Add all terms
    const termData = JSON.stringify(args.items.map(item => ({
      term: item.term,
      context: item.context,
      reference: item.reference,
      tags: item.tags
    })));
    const termRes = await poeditor("terms/add", { id: String(id), data: termData });

    // Step 2: Add all translations
    const translationPayload = args.items.map(item => ({
      term: item.term,
      context: item.context ?? "",
      translation: item.translation.plural
        ? { plural: item.translation.plural }
        : { content: item.translation.content, fuzzy: item.translation.fuzzy ? 1 : 0 }
    }));
    const translationData = JSON.stringify(translationPayload);
    const translationRes = await poeditor("translations/add", {
      id: String(id),
      language: args.language,
      data: translationData
    });

    // Return combined result
    const result = {
      terms_added: termRes.result?.terms ?? termRes.result,
      translations_added: translationRes.result ?? {}
    };
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }
);

POEditor MCP Server