Installation

Choose your preferred installation method

Global Installation

Install Polygot globally for use across all your projects

npm install -g polygot

Local Installation

Install locally for project-specific configurations

npm install polygot
npx polygot --help

Commands Reference

Complete guide to all available commands

extract

Extract Strings

Scans source files for translatable attributes and generates base localization files. 

polygot extract <source> <language> <output> [options]

Options

Option Description Default
-a, --attributes Comma-separated attributes to scan (supports wildcards) title,alt,placeholder
--no-progress Disables the console progress bar -
Example 
polygot extract ./src en ./locales \
  --attributes "title,placeholder,aria*"
translate

Translate Strings

Uses AI to generate high-quality translations for target languages. 

polygot translate <source> <languages> <output> [options]

Options

Option Description Default
-k, --api-key OpenAI API key (use environment variable for security) -
-m, --model OpenAI model for translation gpt-4o-mini
-c, --context Provide context for better translation quality -
-t, --tone Translation tone (formal, casual, neutral) neutral
Example 
export OPENAI_API_KEY=sk-...
polygot translate ./src es,fr ./locales \
  --context "E-commerce checkout" \
  --tone formal
config

Configuration File

Use configuration files for repeatable translation workflows.

Initialize Config

polygot init

Run Translation

polygot translate-config

Web Integration

<polygot-translator>

A lightweight, framework-agnostic web component that adds multi-language support and SEO optimization to any website without wrapping text or rewriting HTML.

Core Features

  • Automatic language detection from URL
  • Language persistence (localStorage)
  • Instant language switching (no reload)
  • Translates Text nodes & Attributes

SEO Optimized

Automatically handles SEO tags without manual configuration:

  • • <html lang> attributes
  • • hreflang links
  • • Canonical URLs
  • • Open Graph & Meta Description

Installation

No build tools required. Add the component to your HTML (preferably near body). 

<script src="https://unpkg.com/polygot"></script>

Basic Usage

That’s it. All visible text on the page will now be translatable. 

<polygot-translator
  loc="/locales"
  languages="en,es,fr"
  default-lang="en"
></polygot-translator>

Translation Files

Create a folder for translations (default: /locales). Keys must exactly match the original text.

Example: /locales/es.json 

{
  "Hello World": "Hola Mundo",
  "Contact Us": "Contáctanos",
  // SEO Metatags
  "meta.title": "Mi sitio web",
  "meta.description": "Este es un sitio web multilingüe",
  "meta.og:title": "Mi sitio web",
  "meta.og:description": "Contenido en español"
}

language-change Hook

Run a custom function on language change.

document.addEventListener("language-change", (event) => {
  console.log("Language changed:", event.detail);
});
Property Type Description
previousLang string The language code before the change
currentLang string The new active language code
translations object The loaded translation object for current language
timestamp number Unix timestamp when the change occurred

JavaScript API

Control the translator programmatically.

Change Language

// Switch language
document
  .querySelector("polygot-translator")
  .changeLanguage("fr");

Sitemap Generation

// Get language-aware URLs
const data = document
  .querySelector("polygot-translator")
  .generateSitemapData();

Debugging

// View detection logic
document
  .querySelector("polygot-translator")
  .getDetectionInfo();

Events

document.addEventListener(
  "polygot-ready", 
  (e) => console.log(e.detail)
);

CI/CD Workflows

Automate your translation pipeline

GitHub Actions Example

Automated translation on every deployment

#!/bin/bash
set -e

# Extract base strings
polygot extract ./src en ./public/locales

# Translate to multiple languages
polygot translate ./src es,fr,de,ja ./public/locales \
  --api-key $OPENAI_API_KEY \
  --context "Enterprise SaaS UI" \
  --tone professional \
  --no-progress

echo "✓ Translation complete"

Fast Processing

Parallel translation for multiple languages

Type Safe

Generated types for translation keys

Auto Updates

Detect and translate new strings automatically

Quality Assured

Context-aware AI translations