@gftdcojp/weblate-nextjs-sdk/README.md

A Next.js SDK for integrating with Weblate translation management system

# Weblate Next.js SDK

[![npm version](https://badge.fury.io/js/@gftdcojp%2Fweblate-nextjs-sdk.svg)](https://badge.fury.io/js/@gftdcojp%2Fweblate-nextjs-sdk)
[![CI](https://github.com/gftdcojp/weblate-nextjs-sdk/workflows/CI/badge.svg)](https://github.com/gftdcojp/weblate-nextjs-sdk/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)

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

```bash
# 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:

```tsx
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

```tsx
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

```tsx
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

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

### WeblateConfig

```typescript
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

```typescript
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

```tsx
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

```tsx
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
```bash
# 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License. See [LICENSE](LICENSE) for details.

## Support

- [GitHub Issues](https://github.com/gftdcojp/weblate-nextjs-sdk/issues)
- [Weblate Documentation](https://docs.weblate.org/)
- [npm Package](https://www.npmjs.com/package/@gftdcojp/weblate-nextjs-sdk)

## 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