SimpleLocalize MCP Server

Instructions

Implementation Reference

• main.py:401-507 (handler)

  The handler function decorated with @mcp.tool(), which registers and implements the 'get_translations_for_keys' tool. It fetches translations for given keys (optionally namespaced) from the SimpleLocalize API, groups them by key/namespace, and returns structured results including all languages, texts, review status, and timestamps.
  @mcp.tool() async def get_translations_for_keys(keys: List[str], namespace: str = None) -> List[dict]: """Get translations for specific translation keys. This endpoint fetches translations for a list of specified keys, optionally filtered by namespace. Returns all available translations for each key across all languages in the project. Args: keys: List of translation keys to fetch translations for (required) namespace: Optional namespace to filter the translations (if not provided, fetches from all namespaces) Returns: List of dictionaries containing: - key (str): Translation key - namespace (str): Namespace for the key - translations (List[dict]): List of translations with fields: - language (str): Language code - text (str): Translation text - reviewStatus (str): Review status (REVIEWED, NOT_REVIEWED) - lastModifiedAt (str): Last modification timestamp """ if not keys: raise ValueError("At least one key is required") try: # Build query parameters for fetching all translations endpoint = "/api/v2/translations" params = [] # If namespace is specified, add it to the query if namespace: params.append(f"namespace={namespace}") # Add size parameter to get more results (max 500 per API docs) params.append("size=500") # Build full endpoint URL with query parameters if params: endpoint += "?" + "&".join(params) result = await make_simplelocalize_request("GET", endpoint) data = result.get("data", []) # Create a set for faster lookup keys_set = set(keys) # Group translations by key and namespace keys_map = {} for item in data: item_key = item.get("key", "") item_namespace = item.get("namespace", "") language = item.get("language", "") text = item.get("text", "") review_status = item.get("reviewStatus", "") last_modified_at = item.get("lastModifiedAt", "") # Only include if the key is in our requested keys list if item_key in keys_set: # If namespace filter is specified, only include matching items if namespace is not None and item_namespace != namespace: continue # Create a unique identifier for the key/namespace combination key_id = f"{item_namespace}:{item_key}" if item_namespace else item_key if key_id not in keys_map: keys_map[key_id] = { "key": item_key, "namespace": item_namespace, "translations": [] } # Add translation if it has content if text and language: keys_map[key_id]["translations"].append({ "language": language, "text": text, "reviewStatus": review_status, "lastModifiedAt": last_modified_at }) # Convert to list and ensure we have entries for all requested keys results = [] for key in keys: # Check both with and without namespace key_id = f"{namespace}:{key}" if namespace else key key_id_no_namespace = key if key_id in keys_map: results.append(keys_map[key_id]) elif key_id_no_namespace in keys_map: results.append(keys_map[key_id_no_namespace]) else: # Add empty entry for keys that don't have translations results.append({ "key": key, "namespace": namespace or "", "translations": [] }) return results except SimpleLocalizeError as e: return [{"error": str(e)}]