Localine SDK for Java

A powerful and easy-to-use Java SDK for the Localine Translation Management API

Features • Installation • Quick Start • Documentation • Examples

---

📋 Table of Contents

• Features
• Installation
• Quick Start
• Core Concepts
• API Reference
  • Terms
  • Translations
  • Labels
  • Languages
  • Import/Export
• Advanced Usage
• Error Handling
• Contributing
• License

---

✨ Features

• 🚀 Simple & Intuitive API - Fluent builder pattern for easy configuration
• 🔒 Type-Safe - Full Java type safety with compile-time checks
• 📦 Complete Coverage - 100% API endpoint coverage for all services
• 🏷️ Term Management - Create, update, delete, lock/unlock terms
• 🌍 Translation Management - Manage translations across multiple locales
• 🎨 Label System - Organize terms with customizable labels
• 📥 Import/Export - Support for multiple formats (JSON, CSV, etc.)
• ⚡ Async Ready - Built on OkHttp for efficient HTTP operations
• 🛡️ Error Handling - Comprehensive exception handling with detailed messages

---

📦 Installation

Maven

Add the GitHub Packages repository to your pom.xml:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/LocalineServices/sdk-java</url>
    </repository>
</repositories>

Then add the dependency:

<dependency>
    <groupId>net.localine.sdk</groupId>
    <artifactId>localine-sdk</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

Gradle

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/LocalineServices/sdk-java")
    }
}

dependencies {
    implementation 'net.localine.sdk:localine-sdk:1.0-SNAPSHOT'
}

---

🚀 Quick Start

import net.localine.sdk.LocalineClient;
import net.localine.sdk.model.Term;
import net.localine.sdk.model.Translation;

public class Example {
    public static void main(String[] args) {
        // Initialize the client
        LocalineClient client = LocalineClient.builder()
            .baseUrl("https://api.yourdomain.net")
            .apiKey("your-api-key")
            .projectId("your-project-id")
            .build();

        try {
            // Create a new term
            Term term = client.terms().create(
                "welcome.message",
                "Welcome message on the home page"
            );

            // Add translations
            client.translations().update(
                term.getId(),
                "en",
                "Welcome to our app!"
            );
            
            client.translations().update(
                term.getId(),
                "de",
                "Willkommen in unserer App!"
            );

            // Fetch all terms
            List<Term> terms = client.terms().getAll();
            terms.forEach(System.out::println);
        } catch (LocalineException exception) {
            System.err.println("Error: " + exception.getMessage());
        } finally {
            client.close();
        }
    }
}

---

🧩 Core Concepts

Client Initialization

The LocalineClient is the main entry point. Use the builder pattern to configure it:

LocalineClient client = LocalineClient.builder()
    .baseUrl("https://api.yourdomain.net")     // API base URL
    .apiKey("tk_...")                          // Your API key
    .projectId("project-uuid")                 // Target project ID
    .timeout(60)                               // Request timeout in seconds (default: 30)
    .build();

Services

The SDK provides six main services:

Service	Purpose	Access Method
TermService	Manage translation terms	client.terms()
TranslationService	Manage translations	client.translations()
LabelService	Manage labels	client.labels()
LanguageService	Manage locales	client.languages()
ExportService	Export translations	client.export()
ImportService	Import translations	client.importData()

---

📚 API Reference

Terms

Manage translation keys and their metadata.

Get All Terms

List<Term> terms = client.terms().getAll();

Get a Single Term

Term term = client.terms().get("term-id");

Create a Term

Term term = client.terms().create(
    "app.button.save",           // Key
    "Save button label"          // Description (optional)
);

Update a Term

Term updated = client.terms().update(
    "term-id",
    "app.button.submit",         // New key (optional)
    "Submit button label"        // New description (optional)
);

Delete a Term

client.terms().delete("term-id");

Search Terms

List<Term> results = client.terms().search("button");

Lock/Unlock Terms

// Lock a single term
Term locked = client.terms().setLocked("term-id", true);

// Unlock a single term
Term unlocked = client.terms().setLocked("term-id", false);

// Lock all terms in project
BulkOperationResponse response = client.terms().lockAll();
System.out.println("Locked " + response.getCount() + " terms");

// Unlock all terms
response = client.terms().unlockAll();

Set Labels on Terms

List<String> labelIds = Arrays.asList("label-id-1", "label-id-2");
Term term = client.terms().setLabels("term-id", labelIds);

---

Translations

Manage translation values for different locales.

Get All Translations for a Locale

Map<String, String> translations = client.translations().getByLocale("en");
// Returns: {"welcome.message": "Welcome!", "app.title": "My App", ...}

Get All Translations (All Locales)

Map<String, Map<String, String>> allTranslations = client.translations().getAll();
// Returns: {"en": {...}, "de": {...}, "fr": {...}}

Get a Specific Translation

String value = client.translations().get("term-key", "en");

Update a Translation

Translation translation = client.translations().update(
    "term-id",
    "en",
    "Updated translation value"
);

Save/Create a Translation

Translation translation = client.translations().save(
    "term-id",
    "en",
    "New translation value"
);

Delete a Translation

client.translations().delete("term-id", "en");

Using the Builder Pattern

Map<String, String> translations = client.translations()
    .getByLocale()
    .locale("en")
    .execute();

---

Labels

Organize and categorize terms with labels.

Get All Labels

List<Label> labels = client.labels().getAll();

Get a Single Label

Label label = client.labels().get("label-id");

Create a Label

Label label = client.labels().create(
    "Feature Request",    // Name
    "#FF5733"            // Color (hex code)
);

Update a Label

Label updated = client.labels().update(
    "label-id",
    "Bug Fix",           // New name (optional)
    "#33FF57"           // New color (optional)
);

Delete a Label

client.labels().delete("label-id");

---

Languages

Manage project locales.

Get All Languages

List<Language> languages = client.languages().getAll();

Get a Specific Language

Language language = client.languages().get("en");

Check if Language is Supported

boolean supported = client.languages().isSupported("de");

Create a New Locale

Locale locale = client.languages().createLocale("es", "Spanish");

---

Import/Export

Export and import translations in various formats.

Export Translations

// Export single locale as JSON
String json = client.export().exportJson("en");

// Export multiple locales
List<String> locales = Arrays.asList("en", "de", "fr");
String export = client.export().exportAllJson(locales);

// Export with custom format
String csv = client.export().exportLocale("en", ExportFormat.CSV);

// Using builder for more control
String export = client.export().builder()
    .locale("en")
    .locale("de")
    .format(ExportFormat.JSON_NESTED)
    .includeEmpty(true)
    .execute();

Import Translations

// Import from file
ImportResponse response = client.importData().importFile(
    Paths.get("/path/to/translations.json")
);

// Import from byte array
byte[] data = Files.readAllBytes(Paths.get("/path/to/file"));
ImportResponse response = client.importData().importData(
    data,
    "translations.json"
);

System.out.println("Imported: " + response.getImported() + " translations");

---

🔥 Advanced Usage

Custom Base URL

LocalineClient client = LocalineClient.builder()
    .baseUrl("http://localhost:3000")  // For local development
    .apiKey("your-api-key")
    .projectId("your-project-id")
    .build();

Custom Timeout

LocalineClient client = LocalineClient.builder()
    .baseUrl("https://api.localine.net")
    .apiKey("your-api-key")
    .projectId("your-project-id")
    .timeout(60)  // 60 seconds
    .build();

Bulk Operations

// Lock all terms before a release
BulkOperationResponse lockResponse = client.terms().lockAll();
System.out.println("Locked " + lockResponse.getCount() + " terms");

// Export all locales
List<String> allLocales = client.languages().getAll()
    .stream()
    .map(Language::getCode)
    .collect(Collectors.toList());

String export = client.export().exportAllJson(allLocales);

Working with Labels

// Create labels for organization
Label bugLabel = client.labels().create("Bug", "#FF0000");
Label featureLabel = client.labels().create("Feature", "#00FF00");

// Tag terms with labels
List<String> labelIds = Arrays.asList(featureLabel.getId());
client.terms().setLabels("term-id", labelIds);

// Get all labels and filter
List<Label> labels = client.labels().getAll();
List<Label> redLabels = labels.stream()
    .filter(l -> l.getColor().equals("#FF0000"))
    .collect(Collectors.toList());

---

⚠️ Error Handling

All SDK methods throw LocalineException for API errors:

try {
    Term term = client.terms().get("invalid-id");
} catch (LocalineException e) {
    System.err.println("Error: " + e.getMessage());
    // Handle error appropriately
}

Common error scenarios:

• Authentication errors - Invalid API key
• Not found errors - Resource doesn't exist
• Permission errors - Insufficient permissions (e.g., editors trying to lock terms)
• Validation errors - Invalid input data
• Network errors - Connection issues

---

🔑 Best Practices

1. Always close the client when done to release resources:

   try (LocalineClient client = /* ... */) {
       // Use client
   } // Auto-closes

2. Cache the client instance - Don't create a new client for every operation

3. Use meaningful term keys - Follow a consistent naming convention:

   client.terms().create("app.screen.home.title", "Home screen title");
   client.terms().create("app.button.submit", "Submit button");

4. Lock terms before releases to prevent accidental changes:

   client.terms().lockAll();

5. Use labels to organize terms by feature, screen, or status

---

🔧 Requirements

• Java 21+
• Maven 3.6+ or Gradle 7+

Dependencies

The SDK uses the following libraries:

• OkHttp 4.12.0 - HTTP client
• Gson 2.13.2 - JSON serialization
• Lombok 1.18.42 - Boilerplate reduction

---

📝 License

This project is licensed under the MIT License.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📞 Support

• Documentation: API Documentation
• Issues: GitHub Issues
• Email: private.httxmxritz@gmail.com
• Discord: itzmxritz

---

Made with ❤️ by ItzMxritz & LeonJS_

GitHub