Integration Guide

{
  "translations": {
    "auth": {
      "login": {
        "title": "Sign In",
        "button": "Log In",
        "forgot": "Forgot password?"
      }
    }
  }
}

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="auth_login_title">Sign In</string>
  <string name="auth_login_button">Log In</string>
  <string name="auth_login_forgot">Forgot password?</string>
</resources>

"auth.login.title" = "Sign In";
"auth.login.button" = "Log In";
"auth.login.forgot" = "Forgot password?";

{
  "sourceLanguage": "en",
  "version": "1.0",
  "strings": {
    "auth.login.title": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Sign In"
          }
        }
      }
    }
  }
}

interface TranslationCache {
  translations: Record<string, string>;
  etag: string;
}

class WiredStringsClient {
  private baseURL: string;
  private token: string;
  private cache = new Map<string, TranslationCache>();

  constructor(baseURL: string, token: string) {
    this.baseURL = baseURL;
    this.token = token;
  }

  async fetch(project: string, locale: string): Promise<Record<string, string>> {
    const key = `${project}:${locale}`;
    const url = `${this.baseURL}/v1/translations/${project}/${locale}`;
    const headers: Record<string, string> = {
      Authorization: `Bearer ${this.token}`,
    };

    const cached = this.cache.get(key);
    if (cached) headers['If-None-Match'] = cached.etag;

    const resp = await fetch(url, { headers });
    if (resp.status === 304 && cached) return cached.translations;

    const data = await resp.json();
    const etag = resp.headers.get('ETag') ?? '';
    this.cache.set(key, { translations: data.translations, etag });
    return data.translations;
  }
}

// Usage
const client = new WiredStringsClient(
  'https://api.wiredstrings.app',
  process.env.WIREDSTRINGS_TOKEN!
);
const translations = await client.fetch('my-project', 'en');

import os, requests

class WiredStringsClient:
    def __init__(self, base_url: str, token: str):
        self.base_url = base_url
        self.token = token
        self._cache: dict[str, dict[str, str]] = {}
        self._etags: dict[str, str] = {}

    def fetch(self, project: str, locale: str) -> dict[str, str]:
        key = f"{project}:{locale}"
        url = f"{self.base_url}/v1/translations/{project}/{locale}"
        headers = {"Authorization": f"Bearer {self.token}"}

        if key in self._etags:
            headers["If-None-Match"] = self._etags[key]

        resp = requests.get(url, headers=headers)
        if resp.status_code == 304:
            return self._cache[key]

        resp.raise_for_status()
        data = resp.json()
        self._cache[key] = data["translations"]
        self._etags[key] = resp.headers.get("ETag", "")
        return data["translations"]

# Usage
client = WiredStringsClient(
    "https://api.wiredstrings.app",
    os.environ["WIREDSTRINGS_TOKEN"]
)
translations = client.fetch("my-project", "en")

// npm install @wiredstrings/sdk

// SSR — pages/index.tsx
import { getServerSideTranslations } from '@wiredstrings/sdk/next';

export const getServerSideProps = async (ctx) => {
  const translations = await getServerSideTranslations(
    ctx.locale ?? 'en-US',
    { projectId: process.env.WS_PROJECT_ID, apiToken: process.env.WS_API_TOKEN }
  );
  return { props: { ...translations } };
};

// SSG with ISR — pages/index.tsx
import { getStaticTranslations } from '@wiredstrings/sdk/next';

export const getStaticProps = async (ctx) => {
  const translations = await getStaticTranslations(ctx.locale ?? 'en-US', { ... });
  return { props: { ...translations }, revalidate: 3600 };
};

// npm install @wiredstrings/sdk i18next react-i18next

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import { WiredStringsBackend } from '@wiredstrings/sdk/i18next';

i18n
  .use(WiredStringsBackend)
  .use(initReactI18next)
  .init({
    backend: {
      projectId: process.env.WS_PROJECT_ID,
      // Use server-side env vars only — do not expose write-scoped tokens in the browser
      apiToken: process.env.WS_API_TOKEN,
    },
    lng: 'en-US',
    fallbackLng: 'en-US',
    interpolation: { escapeValue: false },
  });

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

// Custom backend that fetches from your proxy
const WiredStringsBackend = {
  type: 'backend' as const,
  init() {},
  read(language: string, _namespace: string, callback: Function) {
    // Proxy through your backend — never expose API tokens client-side
    fetch(`/api/translations/${language}`)
      .then(res => res.json())
      .then(data => callback(null, data.translations))
      .catch(err => callback(err, null));
  },
};

i18n
  .use(WiredStringsBackend)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

// In your components:
// const { t } = useTranslation();
// t('auth.login.title') → "Sign In"

// app/[locale]/layout.tsx
import { getTranslations } from '@/lib/wiredstrings';

export default async function LocaleLayout({
  children, params,
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  const translations = await getTranslations(params.locale);
  return (
    <TranslationProvider translations={translations} locale={params.locale}>
      {children}
    </TranslationProvider>
  );
}

// lib/wiredstrings.ts (runs server-side only)
const cache = new Map<string, { data: Record<string, string>; etag: string }>();

export async function getTranslations(locale: string) {
  const headers: Record<string, string> = {
    Authorization: `Bearer ${process.env.WIREDSTRINGS_TOKEN}`,
  };

  const cached = cache.get(locale);
  if (cached) headers['If-None-Match'] = cached.etag;

  const res = await fetch(
    `https://api.wiredstrings.app/v1/translations/my-project/${locale}`,
    { headers, next: { revalidate: 300 } }
  );

  if (res.status === 304 && cached) return cached.data;

  const json = await res.json();
  cache.set(locale, { data: json.translations, etag: res.headers.get('ETag') ?? '' });
  return json.translations;
}

// Fetch translations from your backend proxy
async function loadTranslations(locale) {
  const res = await fetch(`/api/translations/${locale}`);
  const data = await res.json();
  return data.translations;
}

// Simple translation function
let translations = {};

async function initI18n(locale) {
  translations = await loadTranslations(locale);
}

function t(key, vars = {}) {
  let value = translations[key] || key;
  for (const [k, v] of Object.entries(vars)) {
    value = value.replace(new RegExp(`{{\\s*${k}\\s*}}`, 'g'), v);
  }
  return value;
}

// Usage
await initI18n('en');
document.querySelector('h1').textContent = t('dashboard.welcome', { name: 'John' });

import java.net.HttpURLConnection
import java.net.URL

class WiredStringsClient(
    private val baseURL: String,
    private val token: String
) {
    /**
     * Download Android XML strings for a locale.
     * In production, prefer downloading in CI/CD and bundling in res/values/.
     */
    fun downloadStrings(project: String, locale: String): String {
        val url = URL("$baseURL/v1/translations/$project/$locale?format=android_xml")
        val conn = url.openConnection() as HttpURLConnection
        conn.setRequestProperty("Authorization", "Bearer $token")
        return conn.inputStream.bufferedReader().readText()
    }
}

// CI/CD — download and save to res/values:
// curl -H "Authorization: Bearer $TOKEN" \
//   "https://api.wiredstrings.app/v1/translations/my-app/en?format=android_xml" \
//   -o app/src/main/res/values/strings.xml
//
// curl -H "Authorization: Bearer $TOKEN" \
//   "https://api.wiredstrings.app/v1/translations/my-app/de?format=android_xml" \
//   -o app/src/main/res/values-de/strings.xml

# Requires the WiredStrings composite action in your repo:
# see: docs/DEVELOPER_INTEGRATIONS.md — GitHub Action section

name: Sync Translations
on:
  schedule:
    - cron: '0 6 * * 1'
  workflow_dispatch:
    inputs:
      command:
        type: choice
        options: [pull, push]
        default: pull

jobs:
  sync:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/translations
        with:
          api-token: ${{ secrets.WIREDSTRINGS_API_TOKEN }}
          command: ${{ github.event.inputs.command || 'pull' }}
      - uses: peter-evans/create-pull-request@v7
        with:
          commit-message: 'chore: update translations from WiredStrings'
          title: 'Update translations from WiredStrings'
          branch: chore/update-translations

name: Download Translations

on:
  workflow_dispatch:
  schedule:
    - cron: '0 6 * * *' # daily at 6 AM

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Download translations
        env:
          WIREDSTRINGS_TOKEN: ${{ secrets.WIREDSTRINGS_TOKEN }}
        run: bash scripts/download-translations.sh
      - name: Commit if changed
        run: |
          git diff --quiet src/locales/ && exit 0
          git config user.name "github-actions"
          git config user.email "actions@github.com"
          git add src/locales/
          git commit -m "chore: update translations"
          git push

version: 2.1

jobs:
  sync-translations:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run:
          name: Download translations
          command: bash scripts/download-translations.sh
      - run:
          name: Commit if changed
          command: |
            git diff --quiet src/locales/ && exit 0
            git config user.name "circleci"
            git config user.email "ci@circleci.com"
            git add src/locales/
            git commit -m "chore: update translations"
            git push

workflows:
  nightly-sync:
    triggers:
      - schedule:
          cron: "0 6 * * *"
          filters:
            branches:
              only: main
    jobs:
      - sync-translations:
          context: wiredstrings

// Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    triggers { cron('0 6 * * *') }
    environment {
        WIREDSTRINGS_TOKEN = credentials('wiredstrings-token')
    }
    stages {
        stage('Download Translations') {
            steps { sh 'bash scripts/download-translations.sh' }
        }
        stage('Commit Changes') {
            steps {
                sh """
                    git diff --quiet src/locales/ && exit 0
                    git config user.name "jenkins"
                    git config user.email "ci@jenkins"
                    git add src/locales/
                    git commit -m "chore: update translations"
                    git push
                """
            }
        }
    }
}