Weblate MCP Server

Instructions

Implementation Reference

• src/tools/translations.tool.ts:302-378 (handler)

  The handler function decorated with @Tool decorator. Handles input validation via Zod schema, calls the WeblateApiService to find translations, groups results by component/language, formats the output, and handles errors.

  @Tool({
    name: 'findTranslationsForKey',
    description: 'Find all translations for a specific key across all components and languages in a project',
    parameters: z.object({
      projectSlug: z.string().describe('The slug of the project'),
      key: z.string().describe('The exact translation key to find'),
    }),
  })
  async findTranslationsForKey({
    projectSlug,
    key,
  }: {
    projectSlug: string;
    key: string;
  }) {
    try {
      const results = await this.weblateApiService.findTranslationsForKey(
        projectSlug,
        key,
      );
  
      if (results.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `No translations found for key "${key}" in project "${projectSlug}"`,
            },
          ],
        };
      }
  
      // Group by component and language for better readability
      const groupedResults = results.reduce((acc: Record<string, Unit[]>, translation) => {
        const component = translation.web_url?.split('/')[4] || 'unknown';
        const language = translation.web_url?.split('/')[6] || 'unknown';
        const groupKey = `${component}/${language}`;
        
        if (!acc[groupKey]) {
          acc[groupKey] = [];
        }
        acc[groupKey].push(translation);
        return acc;
      }, {});
  
      const formattedResults = Object.entries(groupedResults)
        .map(([groupKey, translations]) => {
          const [component, language] = groupKey.split('/');
          const translationList = translations.map(this.formatTranslationResult).join('\n');
          return `**${component} (${language}):**\n${translationList}`;
        })
        .join('\n\n');
  
      return {
        content: [
          {
            type: 'text',
            text: `Found ${results.length} translations for key "${key}" in project "${projectSlug}":\n\n${formattedResults}`,
          },
        ],
      };
    } catch (error) {
      this.logger.error(
        `Failed to find translations for key "${key}" in ${projectSlug}`,
        error,
      );
      return {
        content: [
          {
            type: 'text',
            text: `Error finding translations for key "${key}" in project "${projectSlug}": ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/translations.tool.ts:305-308 (schema)

  Zod schema defining the input parameters for the tool: projectSlug and key.

  parameters: z.object({
    projectSlug: z.string().describe('The slug of the project'),
    key: z.string().describe('The exact translation key to find'),
  }),

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

  Registration of the WeblateTranslationsTool class in the NestJS AppModule providers array, making the tool available to the MCP server.

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

• src/services/weblate/translations.service.ts:279-302 (helper)

  Core helper function that implements the search logic by querying Weblate units API with context:"key" filter to find all translations for the specific key.

  async findTranslationsForKey(
    projectSlug: string,
    key: string,
    componentSlug?: string,
  ): Promise<Unit[]> {
    try {
      const searchResult = await this.searchTranslations(
        projectSlug,
        componentSlug,
        undefined,
        `context:"${key}"`,
      );
  
      return searchResult.results;
    } catch (error) {
      this.logger.error(
        `Failed to find translations for key "${key}" in project ${projectSlug}`,
        error,
      );
      throw new Error(
        `Failed to find translations for key: ${error.message}`,
      );
    }
  }

• src/services/weblate-api.service.ts:148-158 (helper)

  Intermediate helper in WeblateApiService that delegates the findTranslationsForKey call to the underlying translations service.

  async findTranslationsForKey(
    projectSlug: string,
    key: string,
    componentSlug?: string,
  ): Promise<Unit[]> {
    return this.translationsService.findTranslationsForKey(
      projectSlug,
      key,
      componentSlug,
    );
  }