@transglot/lsp

One editor-agnostic Language Server that brings transglot's editor intelligence to every LSP client, from a single TypeScript codebase: VS Code, Neovim, JetBrains (2023.2+ via LSP4IJ), Sublime Text, and Helix. Instead of re-implementing the same features per editor, each editor gets them by launching this one server.

Features (v1)

All of these reuse the same ported core (the Bearer API client, the RFC-7807 error handling, the URL security validator, and the position-tracking JSON scanner) that the VS Code extension uses.

• Diagnostics: for JSON-family i18n source files (json_flat, json_nested, laravel_json, flutter_arb) that match a source rule in your transglot.json, each source key that is missing a (non-blank) translation in a configured target locale is flagged in the Problems/diagnostics panel. Target locales are pulled from the server via GET /pull.

• Hover: hovering a key shows its translations in every target locale.

• CodeLens: a compact per-key summary line, e.g. fr: Bonjour · de: Hallo · es: Hola. A locale with no translation shows as —.

• Code action "Extract to transglot key" (the headline): put the cursor on, or select, a hardcoded string literal in a .js / .ts / .jsx / .tsx file and this action:

  1. inserts a new "<key>": "<the string>" into your messages JSON file (a slug is generated from the string, de-duplicated against existing keys), and
  2. replaces the literal with an i18n call, t('<key>') by default.

  It also offers to run the transglot.pushKey command, which pushes the updated messages file to your project via POST /push so the new key lands server-side.

Configuration

The server takes all of its configuration from the LSP initializationOptions your client sends on initialize:

| Option | Meaning | Default | | -------------- | -------------------------------------------------------------- | ------------------ | | serverUrl | Base URL of your transglot server | (required) | | token | Project access token (tgl_…) | (required) | | configPath | Path to transglot.json, relative to the workspace root | transglot.json| | i18nFunction | The i18n function the code action calls | t | | messagesFile | Messages JSON file the code action writes to / pushes | (for extract) | | format | FileFormat of messagesFile (used by push) | json_flat |

Security

• The token is pinned to the serverUrl it was configured with and is sent only as Authorization: Bearer … to that origin.
• serverUrl must be https; plaintext http is allowed only for loopback hosts (localhost, 127.0.0.1, ::1) for local development. Anything else is refused before the token is ever sent.
• The token is never logged, not to the LSP trace and not to diagnostics.

Running from source

This package is not published to npm (the transglot-lsp bin name is a placeholder to be claimed on first publish). Build it locally and point your editor at the built entry:

cd packages/lsp
npm install
npm run build      # → dist/server.js (an executable stdio server)
npm test           # vitest: pure core + feature logic
npm run typecheck

The server speaks LSP over stdio. The absolute path to launch is packages/lsp/dist/server.js (or node packages/lsp/dist/server.js).

Wiring it to your editor

VS Code (a ~20-line client)

A minimal extension extension.ts using vscode-languageclient:

import { workspace, type ExtensionContext } from 'vscode';
import {
    LanguageClient,
    TransportKind,
    type ServerOptions,
    type LanguageClientOptions,
} from 'vscode-languageclient/node';

let client: LanguageClient;

export function activate(_context: ExtensionContext) {
    const serverOptions: ServerOptions = {
        run: { module: '/abs/path/to/packages/lsp/dist/server.js', transport: TransportKind.stdio },
        debug: { module: '/abs/path/to/packages/lsp/dist/server.js', transport: TransportKind.stdio },
    };
    const clientOptions: LanguageClientOptions = {
        documentSelector: [{ language: 'json' }, { language: 'typescript' }, { language: 'typescriptreact' }, { language: 'javascript' }, { language: 'javascriptreact' }],
        initializationOptions: {
            serverUrl: 'https://api.transglot.ai',
            token: process.env.TRANSGLOT_TOKEN, // or read from SecretStorage
            messagesFile: 'src/messages/en.json',
            i18nFunction: 't',
            format: 'json_flat',
        },
    };
    client = new LanguageClient('transglot', 'transglot', serverOptions, clientOptions);
    client.start();
}

export function deactivate() { return client?.stop(); }

The bundled @transglot/vscode extension is the richer, first-class VS Code experience; this LSP client is for parity and for editors without a native extension.

Neovim (nvim-lspconfig / native LSP)

vim.lsp.config('transglot', {
  cmd = { 'node', '/abs/path/to/packages/lsp/dist/server.js' },
  filetypes = { 'json', 'javascript', 'javascriptreact', 'typescript', 'typescriptreact' },
  root_markers = { 'transglot.json', '.git' },
  init_options = {
    serverUrl = 'https://api.transglot.ai',
    token = os.getenv('TRANSGLOT_TOKEN'),
    messagesFile = 'src/messages/en.json',
    i18nFunction = 't',
    format = 'json_flat',
  },
})
vim.lsp.enable('transglot')

(On older setups, the classic require('lspconfig.configs') custom-server registration works too; the important bits are the cmd, filetypes, root_dir, and init_options above.)

JetBrains 2023.2+ (LSP4IJ)

Install the LSP4IJ plugin, then add a New Language Server:

• Command: node /abs/path/to/packages/lsp/dist/server.js

• File name patterns / mappings: *.json, *.js, *.jsx, *.ts, *.tsx

• Configuration → Initialization Options (JSON):

  {
    "serverUrl": "https://api.transglot.ai",
    "token": "tgl_…",
    "messagesFile": "src/messages/en.json",
    "i18nFunction": "t",
    "format": "json_flat"
  }

Sublime Text (LSP) & Helix

Any client that launches a stdio LSP works. For Sublime LSP, add a client with "command": ["node", "/abs/path/to/packages/lsp/dist/server.js"] and put the options under "initializationOptions". For Helix, add a language-server entry in languages.toml with command = "node", args = ["/abs/path/.../dist/server.js"], and the options under [language-server.transglot.config].

Endpoints used

Only real, documented transglot API endpoints over /v1 with a Bearer token: GET /project, GET /pull?format=&locale=, POST /push. There is no key-search or key-list endpoint, and this server does not pretend one exists.

What's tested

The pure logic is fully unit-tested with Vitest (npm test):

• the ported core (client, problem/RFC-7807, URL validator, JSON scanner, missing-diff, config, {locale} matcher);
• the extract-key key-name generation (slug + de-dup) and the WorkspaceEdit computation as pure functions (text + range + config → edits);
• the diagnostics/hover/CodeLens rendering helpers.

The LSP host layer (src/server.ts) is the thin glue that maps document positions ↔ byte offsets and speaks the wire protocol.

License

MIT.