Weblate MCP Server

Instructions

Implementation Reference

• src/tools/translations.tool.ts:166-213 (handler)

  The MCP tool handler function that executes the writeTranslation logic. It calls the WeblateApiService, handles success/error responses, and formats the output using formatTranslationResult.

  async writeTranslation({
    projectSlug,
    componentSlug,
    languageCode,
    key,
    value,
    markAsApproved = false,
  }: {
    projectSlug: string;
    componentSlug: string;
    languageCode: string;
    key: string;
    value: string;
    markAsApproved?: boolean;
  }) {
    try {
      const updatedUnit = await this.weblateApiService.writeTranslation(
        projectSlug,
        componentSlug,
        languageCode,
        key,
        value,
        markAsApproved,
      );
  
      return {
        content: [
          {
            type: 'text',
            text: updatedUnit 
              ? `Successfully updated translation for key "${key}"\n\n${this.formatTranslationResult(updatedUnit)}`
              : `Failed to update translation for key "${key}"`,
          },
        ],
      };
    } catch (error) {
      this.logger.error(`Failed to write translation for key ${key}`, error);
      return {
        content: [
          {
            type: 'text',
            text: `Error writing translation for key "${key}": ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/translations.tool.ts:150-165 (schema)

  Tool metadata including name, description, and Zod input schema for validation.

  @Tool({
    name: 'writeTranslation',
    description: 'Update or write a translation value for a specific key',
    parameters: z.object({
      projectSlug: z.string().describe('The slug of the project'),
      componentSlug: z.string().describe('The slug of the component'),
      languageCode: z.string().describe('The language code (e.g., en, es, fr)'),
      key: z.string().describe('The translation key to update'),
      value: z.string().describe('The new translation value'),
      markAsApproved: z
        .boolean()
        .optional()
        .describe('Whether to mark as approved (default: false)')
        .default(false),
    }),
  })

• src/app.module.ts:65-81 (registration)

  NestJS module providers list that registers the WeblateTranslationsTool containing the writeTranslation tool with the MCP framework.

    providers: [
      WeblateClientService,
      WeblateProjectsService,
      WeblateComponentsService,
      WeblateLanguagesService,
      WeblateTranslationsService,
      WeblateChangesService,
      WeblateApiService,
      WeblateStatisticsService,
      WeblateProjectsTool,
      WeblateComponentsTool,
      WeblateLanguagesTool,
      WeblateTranslationsTool,
      WeblateChangesTool,
      WeblateStatisticsTool,
    ],
  })

• src/services/weblate-api.service.ts:92-108 (helper)

  Helper method in WeblateApiService that proxies the writeTranslation call to the underlying translations service.

  async writeTranslation(
    projectSlug: string,
    componentSlug: string,
    languageCode: string,
    key: string,
    value: string,
    markAsApproved: boolean = false,
  ): Promise<Unit | null> {
    return this.translationsService.writeTranslation(
      projectSlug,
      componentSlug,
      languageCode,
      key,
      value,
      markAsApproved,
    );
  }

• src/services/weblate/translations.service.ts:158-201 (helper)

  Core service implementation that locates the translation unit by key, handles plural forms parsing, and performs the actual Weblate API update using unitsPartialUpdate.

  async writeTranslation(
    projectSlug: string,
    componentSlug: string,
    languageCode: string,
    key: string,
    value: string,
    markAsApproved: boolean = false,
  ): Promise<Unit | null> {
    try {
      // First, find the translation unit by key
      const unit = await this.getTranslationByKey(
        projectSlug,
        componentSlug,
        languageCode,
        key,
      );
  
      if (!unit || !unit.id) {
        throw new Error(`Translation unit not found for key "${key}"`);
      }
  
      const client = this.weblateClientService.getClient();
      
      // Parse plural forms correctly for the target field using language-specific rules
      const targetArray = this.parsePluralForms(value, unit.source, languageCode);
      
      // Update the translation using the units API
      const response = await unitsPartialUpdate({
        client,
        path: { id: unit.id.toString() },
        body: {
          target: targetArray, // Properly parsed plural forms
          state: markAsApproved ? 30 : 20, // 30 = approved, 20 = translated
        },
      });
  
      return response.data as Unit;
    } catch (error) {
      this.logger.error(`Failed to write translation for key ${key}`, error);
      throw new Error(
        `Failed to write translation for key ${key}: ${error.message}`,
      );
    }
  }