@proxylang/sdk

@proxylang/sdk

ProxyLang is an instant website translation service. It translates your website content in real-time and delivers it to users in their preferred language.

How ProxyLang Works

ProxyLang offers two translation approaches:

🚀 Server-Side Proxy (Recommended)

The proxy intercepts requests to your website, translates the content server-side, and delivers fully translated pages to users. Zero flicker, instant load times, perfect SEO.

URL patterns supported:

• /ko-kr/about — Full locale code
• /kr/about — Country code (auto-detected)
• /ko/about — Language code (auto-detected)

With server-side proxy, users receive pre-translated HTML. No JavaScript required.

⚡ Client-Side SDK

For dynamic content rendered by JavaScript frameworks (React, Vue, Next.js, Nuxt, etc.), the SDK translates content in the browser after it renders.

Use the SDK when:

• Your app has client-side routing (SPAs)
• Content is loaded dynamically via AJAX
• You're using the proxy and need to translate JavaScript-rendered content

Installation

npm install @proxylang/sdk
# or
pnpm add @proxylang/sdk
# or
yarn add @proxylang/sdk

Or include via CDN:

<script src="https://unpkg.com/@proxylang/sdk/dist/proxylang-sdk.umd.js"></script>

Quick Start

With Server-Side Proxy (Dynamic Mode)

If you're using ProxyLang's server-side proxy, the SDK only needs to handle new content added by JavaScript:

import { ProxyLang } from '@proxylang/sdk'

ProxyLang.init({
  apiKey: 'pk_live_xxx',
  targetLang: 'ko-KR',
  mode: 'dynamic',  // Only translate new DOM content
})

Standalone (Full Mode)

For client-side only translation:

import { ProxyLang } from '@proxylang/sdk'

ProxyLang.init({
  apiKey: 'pk_live_xxx',
  targetLang: 'es-MX',
  mode: 'full',  // Translate entire page (default)
})

Configuration

ProxyLang.init({
  // Required
  apiKey: 'pk_live_xxx',
  targetLang: 'es-MX',
  
  // Mode
  mode: 'full',  // 'full' (default) or 'dynamic'
  
  // Optional
  sourceLang: 'en',                    // Default source language
  selectors: ['body'],                 // CSS selectors to translate
  exclude: ['.no-translate', 'code'],  // Exclude these selectors
  autoTranslate: true,                 // Translate on page load
  observeMutations: true,              // Watch for DOM changes
  debug: false,                        // Enable console logging
  
  // Callbacks
  onStart: () => {},
  onComplete: (stats) => console.log('Done:', stats),
  onError: (error) => console.error(error),
  onQuotaExceeded: (info) => {
    window.location.href = info.upgradeUrl
  },
})

Mode Options

Mode	Description	Use Case
full	Translates entire page on load	Client-side only apps
dynamic	Only translates new DOM content	With server-side proxy

API Reference

ProxyLang.init(config)

Initialize the SDK. Call once on app startup.

ProxyLang.translate()

Manually trigger translation. Returns stats.

const stats = await ProxyLang.translate()
// { stringsTranslated: 42, cacheHits: 30, cacheMisses: 12, timeMs: 150 }

ProxyLang.setLanguage(langCode)

Change language and re-translate.

await ProxyLang.setLanguage('fr-CA')

ProxyLang.getLanguage()

Get current target language.

ProxyLang.getLanguage()  // 'es-MX'

ProxyLang.clearCache()

Clear all cached translations.

ProxyLang.clearCache()

ProxyLang.destroy()

Clean up the SDK instance.

Language Switcher

With Server-Side Proxy (Redirect)

When using the proxy, switching languages is a simple URL redirect:

function switchLanguage(langCode) {
  // Remove existing language prefix
  const path = window.location.pathname.replace(/^\/[a-z]{2}(-[a-z]{2})?\//i, '/')
  
  // Redirect to new language
  window.location.href = `/${langCode.toLowerCase()}${path}`
}

<select onchange="switchLanguage(this.value)">
  <option value="en-US">English</option>
  <option value="ko-KR">한국어</option>
  <option value="ja-JP">日本語</option>
  <option value="es-MX">Español</option>
</select>

With Client-Side SDK

const changeLanguage = async (lang) => {
  await ProxyLang.setLanguage(lang)
}

Helper Functions

isProxyTranslated()

Check if the current page was served by ProxyLang proxy:

import { isProxyTranslated } from '@proxylang/sdk'

if (isProxyTranslated()) {
  // Page is pre-translated, use dynamic mode
  ProxyLang.init({ mode: 'dynamic', ... })
} else {
  // Full client-side translation
  ProxyLang.init({ mode: 'full', ... })
}

getLanguageFromPath()

Extract language code from URL path:

import { getLanguageFromPath } from '@proxylang/sdk'

const lang = getLanguageFromPath()  // 'ko-kr' from /ko-kr/about

Framework Examples

React

import { useEffect, useState } from 'react'
import { ProxyLang, isProxyTranslated } from '@proxylang/sdk'

function App() {
  useEffect(() => {
    ProxyLang.init({
      apiKey: 'pk_live_xxx',
      targetLang: 'es-MX',
      mode: isProxyTranslated() ? 'dynamic' : 'full',
    })
    
    return () => ProxyLang.destroy()
  }, [])
  
  return <div>Your app content</div>
}

Vue / Nuxt

<script setup>
import { onMounted, onUnmounted } from 'vue'
import { ProxyLang, isProxyTranslated } from '@proxylang/sdk'

onMounted(() => {
  ProxyLang.init({
    apiKey: 'pk_live_xxx',
    targetLang: 'es-MX',
    mode: isProxyTranslated() ? 'dynamic' : 'full',
  })
})

onUnmounted(() => {
  ProxyLang.destroy()
})
</script>

Excluding Content

HTML Attributes

<span data-proxylang-skip>Don't translate this</span>
<div class="proxylang-skip">Or this</div>

HTML Comments

For larger sections:

<!-- @proxylang-do-not-translate-start -->
<div>This entire section stays in the original language</div>
<ul>
  <li>日本語</li>
  <li>한국어</li>
</ul>
<!-- @proxylang-do-not-translate-end -->

Config Exclusions

ProxyLang.init({
  exclude: ['.brand-name', 'code', 'pre', '[data-no-translate]'],
})

Supported Languages

ProxyLang supports 50+ languages including:

• 🇺🇸 English, 🇪🇸 Spanish, 🇫🇷 French, 🇩🇪 German
• 🇯🇵 Japanese, 🇰🇷 Korean, 🇨🇳 Chinese (Simplified & Traditional)
• 🇸🇦 Arabic, 🇮🇱 Hebrew, 🇮🇳 Hindi
• And many more...

Full list at proxylang.dev/languages

Performance

• Edge-cached — Translations cached at edge for instant delivery
• Deduplication — Identical strings translated once
• Batching — All strings sent in a single request
• Persistent cache — LocalStorage caching for return visitors

Pricing

Tier	Included	Price
Free	10,000 tokens	$0
Starter	100,000 tokens	$9/mo
Pro	1M tokens	$49/mo
Business	10M tokens	$199/mo

Only cache misses count toward usage. Cached translations are free.

Get Started

• Sign up at proxylang.dev
• Create an API key
• Install the SDK or configure the proxy
• Start translating!

License

MIT © ProxyLang