DOCSEARCHbyAlgolia
Submit Docs

Glossia Documentation

website·Indexed 32 days ago

https://glossia.ai/docs

Glossia is a localization platform that connects GitHub repositories to LLM-powered translation workflows. It features a configuration-driven approach using L10N.md, progressive refinement for translation quality, a Model Context Protocol (MCP) server for coding agents, and built-in localization analytics and web SDKs.

Tokens
11.5K
Snippets
46
Records
93
Agent score
59%

What's inside Glossia

  1. Overview of Glossia MCP Server capabilities

    Glossia provides a Model Context Protocol (MCP) server that allows coding agents to interact with localization projects. Once connected, agents can query translation status, trigger translations and revisions, inspect configuration and content entries, and access project context for improved code suggestions.

  2. Configure translation rules using L10N.md

    L10N.md is the configuration file that tells Glossia which files to translate, the target languages, where the translated files should be placed, and the context for the translation. A repository can have a root L10N.md and additional scoped files in subdirectories to override settings or add specific guidance.
    ---
source_language: en
model: translation-default
sources:
  "docs/**/*.md": "docs/i18n/{locale}/{relpath}"
targets:
  - es
  - ja
validation:
  - ./scripts/validate-docs.sh
  - --strict
frontmatter: preserve
preserve:
  - placeholders
  - urls
---

Write for software developers. Keep product names and code samples unchanged.

  3. Understand Glossia's server-side translation workflow

    Translation is performed on the Glossia server, not locally via the CLI. The workflow is as follows:

    1. A commit is pushed.
    2. Glossia reads the L10N.md files to plan the work.
    3. Files are translated using the configured model.
    4. A pull request is opened with the results.

    Model Selection: The model is determined per document. If a model: key is specified in L10N.md, that specific account model handle is used; otherwise, the account's default model is applied.

    CLI Limitations: The CLI does not perform planning, translation, validation, inspection, or deletion of translations, nor does it read server translation lockfiles.

  4. Glossia web analytics privacy model

    The Glossia web analytics SDK is designed for privacy and avoids persistent tracking:

    • No Cookies: No client-side cookies are set. A per-tab session ID is stored in sessionStorage and cleared when the tab is closed.
    • No Fingerprinting: The system does not collect Canvas, WebGL, font, or audio fingerprints.
    • Ephemeral Identifiers: Raw IP and User-Agent data are read, hashed with a server secret and daily salt to create a visitor_id, and then immediately discarded.
    • Project Isolation: Visitor IDs are scoped per project; a single browser visiting two different Glossia customers will result in two unrelated visitor IDs.

  5. Send web analytics events to the Glossia API

    The /api/analytics/events endpoint accepts JSON event data from the @glossia/web SDK. The endpoint always responds with a 202 Accepted status, even for malformed payloads or unknown domains, to prevent leaking information about which projects have analytics enabled. Project identification is determined by the site domain (d field); if d is missing, the server falls back to the host of the page URL (u), and then to the request Origin or Referer headers. CORS is open (Access-Control-Allow-Origin: *) as no credentials are required.
    POST /api/analytics/events

  6. Understand Prompt definitions in Glossia

    In the Glossia application runtime, prompt definitions serve as the source-of-truth data for how prompts are managed and executed.

  7. Manage LLM providers using account-scoped models

    Glossia separates repository instructions from model-provider credentials. Model configurations are stored at the account level rather than in the repository. This allows administrators to rotate provider keys or switch LLM models across multiple repositories without modifying the source code of each repository. It also ensures that sensitive provider keys are kept out of source control.

  8. Understand Glossia glossary functionality

    A glossary in Glossia is a curated set of terms that must be rendered consistently across translations for a specific language. It provides guidance to the translation model rather than performing simple string substitution; the model still considers surrounding context. Glossaries are used for individual terms and approved translations, while voice, tone, and formality are handled via Voice configuration and L10N.md.

  9. Manage glossaries in the repository vs. the server

    Glossia merges glossary entries from two sources at translation time:

    Repository-based Glossary (Developer-Authoritative):

    • Location: Defined in L10N.md (terms) and L10N/<locale>.md (translations).
    • Use Case: Terms specific to a codebase, changes that must be coupled with source text via pull requests, or terms that only apply to specific directories (via nested L10N.md files).
    • Priority: Repository entries override server entries for the same term in the languages they translate.

    Server-based Glossary (Linguist-Authoritative):

    • Location: Stored in the Glossia account dashboard, REST API, or MCP server.
    • Use Case: Brand terms/product names applying to multiple repositories, terms managed by linguists without code access, or fixes that need to apply immediately without a pull request.
    • Features: Includes version history, change notes, and accessibility for external agents/integrations via API.

  10. Retry a failed Glossia project setup

    When a project setup fails, you must resolve the underlying prerequisite before triggering a retry. The 'Retry setup' option is only available while the project is in the 'Failed' state to prevent concurrent setup attempts.

    Step-by-step recovery process:

    1. Diagnose the failure: Open the project overview and check the setup progress card for the latest activity and error message.
    2. Fix the prerequisite:
      • For model or provider key issues: Navigate to Settings > Models.
      • For repository access issues: Update the Glossia GitHub App installation in GitHub to grant the necessary permissions.
    3. Trigger Retry: Return to the project overview and select Retry setup. The status will transition from Pending to Running.
    4. Verify: Once the state changes to Completed, review the generated pull request in GitHub.

    Common failure causes to look for:

    • No configured model in the account.
    • Missing or invalid provider keys.
    • Glossia GitHub App lacks repository access.
    • Repository preparation or check failures.

  11. Configure language-specific translation context in Glossia

    To provide special instructions for a specific language (such as formality levels or character set requirements), create a markdown file named after the language code within the L10N/ directory. Glossia merges the content of this override file with the base context for that specific language's translations.
    L10N/
  ja.md

  12. Implement the Glossia progressive refinement loop

    Glossia uses an iterative 'progressive refinement' process to reach production-quality content. Instead of expecting perfection on the first run, users should follow a cycle of drafting, reviewing, and refining to align the output with the product's specific voice and domain nuances.

    The refinement loop consists of four stages:

    1. Draft: Glossia generates a structurally valid first pass using source files and the L10N.md context file.
    2. Review: Teams identify issues using standard pull requests and diffs.
    3. Refine: Feedback is integrated by updating context files and correcting glossary entries, which then feed into the next generation run.
    4. Converge: Repeated cycles narrow the gap to production quality as the system learns from the provided context.