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)}]