searchUnitsWithFilters
Filter and retrieve translation units in Weblate projects by state, source, target, or component using advanced search syntax. Specify project, component, and language for precise results.
Instructions
Search translation units using Weblate's powerful filtering syntax. Supports filters like: state:<translated (untranslated), state:>=translated (translated), component:NAME, source:TEXT, target:TEXT, has:suggestion, etc.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| componentSlug | Yes | The slug of the component | |
| languageCode | Yes | The language code (e.g., sk, cs, fr) | |
| limit | No | Maximum number of results to return (default: 50, max: 200) | |
| projectSlug | Yes | The slug of the project | |
| searchQuery | Yes | Weblate search query using their filter syntax. Examples: "state:<translated" (untranslated), "state:>=translated" (translated), "source:hello", "has:suggestion", "component:common AND state:<translated" |
Implementation Reference
- src/tools/translations.tool.ts:391-446 (handler)The handler function that implements the core logic of the 'searchUnitsWithFilters' tool. It takes parameters, calls the Weblate API service to search units with the given query, handles empty results and errors, and formats the output using a helper function.async searchUnitsWithFilters({ projectSlug, componentSlug, languageCode, searchQuery, limit = 50, }: { projectSlug: string; componentSlug: string; languageCode: string; searchQuery: string; limit?: number; }) { try { const results = await this.weblateApiService.searchUnitsWithQuery( projectSlug, componentSlug, languageCode, searchQuery, Math.min(limit, 200), // Cap at 200 to prevent overwhelming responses ); if (results.length === 0) { return { content: [ { type: 'text', text: `No units found matching query "${searchQuery}" in ${projectSlug}/${componentSlug}/${languageCode}`, }, ], }; } const resultText = this.formatFilteredResults(results, projectSlug, componentSlug, languageCode, searchQuery); return { content: [ { type: 'text', text: resultText, }, ], }; } catch (error) { this.logger.error('Failed to search units with filters', error); return { content: [ { type: 'text', text: `Error searching units: ${error.message}`, }, ], isError: true, }; } }
- src/tools/translations.tool.ts:380-390 (registration)The @Tool decorator that registers the 'searchUnitsWithFilters' tool, including its name, description, and Zod input schema for validation.@Tool({ name: 'searchUnitsWithFilters', description: 'Search translation units using Weblate\'s powerful filtering syntax. Supports filters like: state:<translated (untranslated), state:>=translated (translated), component:NAME, source:TEXT, target:TEXT, has:suggestion, etc.', 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., sk, cs, fr)'), searchQuery: z.string().describe('Weblate search query using their filter syntax. Examples: "state:<translated" (untranslated), "state:>=translated" (translated), "source:hello", "has:suggestion", "component:common AND state:<translated"'), limit: z.number().optional().default(50).describe('Maximum number of results to return (default: 50, max: 200)'), }), })
- Private helper method used by the handler to format and summarize the search results for user-friendly display, including status determination and truncation for long lists.private formatFilteredResults(results: Unit[], projectSlug: string, componentSlug: string, languageCode: string, searchQuery: string): string { if (results.length === 0) { return `No units found in ${projectSlug}/${componentSlug}/${languageCode} matching query: ${searchQuery}`; } const formattedResults = results .slice(0, 50) // Limit to 50 for readability .map(unit => { const sourceText = unit.source && Array.isArray(unit.source) ? unit.source.join('') : (unit.source || '(empty)'); const targetText = unit.target && Array.isArray(unit.target) ? unit.target.join('') : (unit.target || '(empty)'); // Determine status based on state let status = '❓ Unknown'; if (unit.state === 0) status = '❌ Untranslated'; else if (unit.state === 10) status = '🔄 Needs Editing'; else if (unit.state === 20) status = '✅ Translated'; else if (unit.state === 30) status = '✅ Approved'; else if (unit.state === 100) status = '🔒 Read-only'; return `**Key:** ${unit.context || '(no context)'} **Source:** ${sourceText} **Target:** ${targetText} **Status:** ${status} **Location:** ${unit.location || '(none)'} **Note:** ${unit.note || '(none)'} **ID:** ${unit.id}`; }) .join('\n\n'); const totalText = results.length > 50 ? `\n\n*Showing first 50 of ${results.length} units*` : ''; return `Found ${results.length} units in ${projectSlug}/${componentSlug}/${languageCode} matching query "${searchQuery}":\n\n${formattedResults}${totalText}`; }