@gftdcojp/weblate-nextjs-sdk

Weblate Next.js SDK

A powerful and easy-to-use SDK for integrating Weblate translation management system with Next.js applications.

Features

• 🌐 Full Weblate API Integration - Complete support for Weblate's REST API
• ⚡ React Hooks - Modern React hooks for managing translations and languages
• 🎯 TypeScript Support - Full TypeScript support with comprehensive type definitions
• 🔄 Real-time Updates - Live translation updates using SWR
• 🌍 Multi-language Support - Easy language switching and management
• 🎨 Next.js Optimized - Built specifically for Next.js applications
• 📦 Lightweight - Minimal dependencies and optimized bundle size

Installation

# Using pnpm (recommended)
pnpm install @gftdcojp/weblate-nextjs-sdk

# Using npm
npm install @gftdcojp/weblate-nextjs-sdk

# Using yarn
yarn add @gftdcojp/weblate-nextjs-sdk

Quick Start

1. Setup WeblateProvider

Wrap your app with the WeblateProvider:

import { WeblateProvider } from '@gftdcojp/weblate-nextjs-sdk';

const weblateConfig = {
  baseUrl: process.env.NEXT_PUBLIC_WEBLATE_URL,
  apiKey: process.env.WEBLATE_API_KEY,
};

function App({ Component, pageProps }) {
  return (
    <WeblateProvider config={weblateConfig} defaultLanguage="en">
      <Component {...pageProps} />
    </WeblateProvider>
  );
}

2. Use Translation Hooks

import { useTranslation, useWeblate } from '@gftdcojp/weblate-nextjs-sdk';

function MyComponent() {
  const { client, currentLanguage } = useWeblate();
  const { translations, isLoading, error } = useTranslation({
    componentSlug: 'my-component',
    languageCode: currentLanguage,
    client,
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h1>{translations['welcome'] || 'Welcome'}</h1>
    </div>
  );
}

3. Language Management

import { useLanguage, useWeblate } from '@gftdcojp/weblate-nextjs-sdk';

function LanguageSelector() {
  const { client } = useWeblate();
  const { languages, currentLanguage, setLanguage } = useLanguage({
    client,
  });

  return (
    <select
      value={currentLanguage?.code || ''}
      onChange={(e) => setLanguage(e.target.value)}
    >
      {languages.map((lang) => (
        <option key={lang.code} value={lang.code}>
          {lang.name}
        </option>
      ))}
    </select>
  );
}

Configuration

Environment Variables

NEXT_PUBLIC_WEBLATE_URL=https://your-weblate-instance.com
WEBLATE_API_KEY=your-api-key

WeblateConfig

interface WeblateConfig {
  baseUrl: string;       // Weblate instance URL
  apiKey: string;        // API key for authentication
  timeout?: number;      // Request timeout (default: 10000ms)
  retries?: number;      // Number of retries (default: 3)
}

API Reference

Hooks

useWeblate()

Returns the Weblate context with client and language state.

useTranslation(options)

Fetches translations for a specific component and language.

Options:

• componentSlug: string - Component slug
• languageCode: string - Language code
• client: WeblateClient - Weblate client instance

useLanguage(options)

Manages available languages and current language selection.

Options:

• client: WeblateClient - Weblate client instance
• defaultLanguage?: string - Default language code

useT(key, defaultValue?, options?)

Simple hook for getting a single translation.

useUpdateTranslation(client)

Hook for updating translations.

Client Methods

WeblateClient

• getProjects() - Get all projects
• getProject(slug) - Get specific project
• getComponents(projectSlug) - Get project components
• getTranslations(componentSlug) - Get component translations
• getTranslation(componentSlug, languageCode) - Get specific translation
• getUnits(translationId) - Get translation units
• updateUnit(unitId, target) - Update translation unit
• getStatistics(componentSlug, languageCode) - Get translation statistics
• searchUnits(query, component?, language?) - Search translation units
• getLanguages() - Get available languages

Advanced Usage

Custom Client

import { createWeblateClient } from '@gftdcojp/weblate-nextjs-sdk';

const client = createWeblateClient({
  baseUrl: 'https://your-weblate-instance.com',
  apiKey: 'your-api-key',
  timeout: 5000,
  retries: 2,
});

// Use client directly
const projects = await client.getProjects();

Error Handling

import { WeblateApiError } from '@gftdcojp/weblate-nextjs-sdk';

function MyComponent() {
  const { translations, error } = useTranslation(options);

  if (error) {
    if (error instanceof WeblateApiError) {
      console.error('API Error:', error.code, error.message);
    }
    return <div>Translation error occurred</div>;
  }

  return <div>{translations['key']}</div>;
}

Server-Side Rendering

import { GetServerSideProps } from 'next';
import { createWeblateClient } from '@gftdcojp/weblate-nextjs-sdk';

export const getServerSideProps: GetServerSideProps = async (context) => {
  const client = createWeblateClient({
    baseUrl: process.env.WEBLATE_URL,
    apiKey: process.env.WEBLATE_API_KEY,
  });

  const translations = await client.getTranslation(
    'my-component',
    context.locale || 'en'
  );

  return {
    props: {
      translations,
    },
  };
};

Type Definitions

The SDK provides comprehensive TypeScript definitions for all Weblate API objects:

• WeblateProject
• WeblateComponent
• WeblateLanguage
• WeblateTranslation
• WeblateUnit
• WeblateStats
• And more...

Versioning

This project uses CalVer (Calendar Versioning) with the format YYYY.MM.MICRO:

• YYYY: 4-digit year (e.g., 2025)
• MM: 2-digit month (e.g., 07 for July)
• MICRO: Incremental release number within the month (starting from 1)

Examples

• 2025.07.1 - First release in July 2025
• 2025.07.2 - Second release in July 2025
• 2025.08.1 - First release in August 2025

Release Commands

# Micro release (increment within current month)
pnpm run calver
pnpm run release

# Major release (reset to .1 for current month)
pnpm run calver:major  
pnpm run release:major

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests
• Submit a pull request

License

MIT License. See LICENSE for details.

Support

• GitHub Issues
• Weblate Documentation
• npm Package

Roadmap

• Support for Weblate's GraphQL API
• Built-in caching strategies
• Offline translation support
• Translation management UI components
• Integration with Next.js i18n
• Support for translation editing
• Batch translation operations
• Advanced filtering and search
• Translation validation hooks
• Performance optimization tools