SimpleLocalize MCP Server

Instructions

Implementation Reference

• main.py:314-400 (handler)

  Handler function for the 'get_missing_translations' tool. It fetches all translations from the SimpleLocalize API, identifies keys missing translations in some languages, and returns a list of those keys with their existing translations.

  @mcp.tool()
  async def get_missing_translations() -> List[dict]:
      """Get a list of translation keys that have missing translations.
      
      This endpoint returns translation keys along with their existing translations,
      focusing on keys that are missing translations in one or more languages.
      To identify missing translations, the function compares each key against all
      languages that have at least one translation in the project.
      
      Returns:
          List of dictionaries containing:
              - key (str): Translation key
              - namespace (str): Namespace for the key (if applicable)
              - description (str): Description for translators (if applicable)
              - translations (List[dict]): List of existing translations with fields:
                  - language (str): Language code
                  - text (str): Translation text
      """
      try:
          # Get all translation keys with their translations
          result = await make_simplelocalize_request(
              "GET",
              "/api/v2/translations"
          )
          
          data = result.get("data", [])
          
          # First pass: collect all languages used in the project
          all_languages = set()
          keys_map = {}
          
          for item in data:
              key = item.get("key", "")
              namespace = item.get("namespace", "")
              description = item.get("description", "")
              language = item.get("language", "")
              text = item.get("text", "")
              
              if language:
                  all_languages.add(language)
              
              # Create a unique identifier for the key (including namespace)
              key_id = f"{namespace}:{key}" if namespace else key
              
              if key_id not in keys_map:
                  keys_map[key_id] = {
                      "key": key,
                      "namespace": namespace,
                      "description": description,
                      "translations": [],
                      "languages_with_translations": set()
                  }
              
              # Add translation if text exists
              if text and language:
                  keys_map[key_id]["translations"].append({
                      "language": language,
                      "text": text
                  })
                  keys_map[key_id]["languages_with_translations"].add(language)
          
          # Second pass: filter for keys that have missing translations
          missing_translations = []
          
          for key_data in keys_map.values():
              # Check if this key is missing translations in any language
              missing_languages = all_languages - key_data["languages_with_translations"]
              
              # Only include keys that have missing translations
              if missing_languages:
                  # Remove the helper set before returning
                  key_result = {
                      "key": key_data["key"],
                      "namespace": key_data["namespace"],
                      "description": key_data["description"],
                      "translations": key_data["translations"]
                  }
                  missing_translations.append(key_result)
          
          if len(missing_translations) == 0:
              return "No missing translations found"
          
          return missing_translations
          
      except SimpleLocalizeError as e:
          return [{"error": str(e)}]