NeoIQ Localize SDK Documentation

The NeoIQ Localize SDK provides a simple and powerful way to integrate NeoIQ Localize's translation capabilities into your applications.

Installation

npm install @neoiq/localize-sdk

Quick Start

import { NeoIQLocalize } from "@neoiq/localize-sdk";
 
async function run() {
  const neoiqLocalize = new NeoIQLocalize({
    apiKey: process.env.NEOIQ_LOCALIZE_API_KEY,
  });
 
  const result = await neoiqLocalize.translate({
    sourceText: "Hello, world!",
    sourceLocale: "en",
    targetLocale: "sv",
    projectId: process.env.NEOIQ_LOCALIZE_PROJECT_ID,
  });
 
  console.log(result.translatedText);
}
 
run();

Authentication

The SDK requires an API key to authenticate requests. Your API key should start with org_. You can obtain an API key from your NeoIQ Localize dashboard.

const neoiqLocalize = new NeoIQLocalize({
  apiKey: process.env.NEOIQ_LOCALIZE_API_KEY,
});

Parameters:

The translate method accepts an object with the following properties:

• projectId (string, required): The ID of your NeoIQ Localize project
• sourceLocale (string, required): The locale code of the source text
• targetLocale (string, required): The locale code to translate into
• sourceText (string, required): The text to translate
• format (string, optional): The format of the source text. Defaults to "string"
• cache (boolean, optional): Whether to use cached translations. Defaults to true

Supported Formats:

• string: Plain text
• json: JSON files
• yaml: YAML files
• properties: Java properties files
• android: Android resource files
• xcode-strings: iOS Strings files
• xcode-stringsdict: iOS Stringsdict files
• xcode-xcstrings: iOS XCStrings files
• md: Markdown files
• mdx: MDX files
• html: HTML files
• js: JavaScript files
• ts: TypeScript files
• po: Gettext PO files
• xliff: XLIFF files
• csv: CSV files
• xml: XML files
• arb: ARB (Application Resource Bundle) files
• ftl: Fluent FTL files
• php: PHP files

Best Practices

1. Cache Management: By default, translations are cached. You can disable caching for specific requests by setting cache: false in the translate parameters.

2. Error Handling: Always implement proper error handling in your application to gracefully handle API errors.

3. API Key Security: Never expose your API key in client-side code. Always keep it secure on your server.

4. Format Selection: Choose the appropriate format for your content type to ensure accurate translations.

Examples

Translating JSON Content

const neoiqLocalize = new NeoIQLocalize({
  apiKey: process.env.NEOIQ_LOCALIZE_API_KEY,
});
 
const jsonContent = {
  greeting: "Hello",
  farewell: "Goodbye"
};
 
const translation = await neoiqLocalize.translate({
  projectId: 'your_project_id',
  sourceLocale: 'en',
  targetLocale: 'fr',
  sourceText: JSON.stringify(jsonContent),
  format: 'json'
});
 
const translatedJson = JSON.parse(translation.translatedText);

Translating Markdown Content

const neoiqLocalize = new NeoIQLocalize({
  apiKey: process.env.NEOIQ_LOCALIZE_API_KEY,
});
 
const markdownContent = "# Welcome\n\nThis is a **markdown** document.";
 
const translation = await neoiqLocalize.translate({
  projectId: 'your_project_id',
  sourceLocale: 'en',
  targetLocale: 'de',
  sourceText: markdownContent,
  format: 'md'
});
 
console.log(translation.translatedText);