### Fine-Grained Install Lingui (NPM)

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Install Lingui CLI, Babel plugin, and React integration using NPM for a cleaner setup.

```bash
# NPM
npm install --save-dev @lingui/cli
npm install --save-dev @lingui/babel-plugin-lingui-macro
npm install @lingui/react
```

--------------------------------

### Install Lingui Meta-package (Yarn)

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Quickly install Lingui with necessary dependencies using Yarn.

```bash
# Yarn
yarn add @translation/lingui
```

--------------------------------

### Fine-Grained Install Lingui (Yarn)

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Install Lingui CLI, Babel plugin, and React integration using Yarn for a cleaner setup.

```bash
# Yarn
yarn add --dev @lingui/cli
yarn add --dev @lingui/babel-plugin-lingui-macro
yarn add @lingui/react
```

--------------------------------

### Install Lingui Meta-package (NPM)

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Quickly install Lingui with necessary dependencies using NPM.

```bash
# NPM
npm install @translation/lingui
```

--------------------------------

### GetText Localization Examples

Source: https://translation.io/docs/guide-to-translate-your-rails-applications

Examples showcasing the GetText syntax for regular translations, pluralization, context-aware translations, and interpolations.

```ruby
# Regular
_("Text to be translated")

# Pluralization
n_("Singular text", "Plural text", number)

# Regular with context
p_("context", "Text to be translated")

# Pluralization with context
np_("context", "Singular text", "Plural text", number)

# Interpolations
_('%{city1} is bigger than %{city2}') % { city1: "NYC", city2: "BXL" }

```

--------------------------------

### Example Error Response for segments/init

Source: https://translation.io/docs/create-library

This example shows a typical JSON response when the 'segments/init' request fails due to missing parameters or incorrect data structure. The 'errors' array provides specific details about the issues.

```json
{
  "errors": [
    "Missing param(s): source_language.",
    "'segments' must be a Hash with target_languages as keys and arrays of segments as values."
  ]
}
```

--------------------------------

### Install Angular Localize Package

Source: https://translation.io/docs/guide-to-translate-your-angular-applications

Installs the necessary Angular localize package. This is a prerequisite for managing translations.

```bash
ng add @angular/localize

```

--------------------------------

### I18n (YAML) Localization Examples

Source: https://translation.io/docs/guide-to-translate-your-rails-applications

Examples demonstrating the use of the default Rails Internationalization API for regular translations, pluralization, and interpolation.

```ruby
# Regular
t('inbox.title')

# Pluralization
t('inbox.message', count: n)

# Interpolation
t('inbox.hello', name: @user.name)

```

--------------------------------

### Translation.io Configuration File

Source: https://translation.io/docs/guide-to-translate-your-angular-applications

Example of the tio.config.json file. Configure your API key, source locale, and target locales.

```json
{
  "api_key": "abcdefghijklmnopqrstuvwxyz123456",
  "source_locale": "en",
  "target_locales": ["fr", "it", "es"]
}

```

--------------------------------

### Install Laravel Package

Source: https://translation.io/docs/guide-to-translate-your-laravel-applications

Add the Translation.io package to your Laravel project using Composer.

```bash
composer require tio/laravel

```

--------------------------------

### Install Translation.io Angular Package

Source: https://translation.io/docs/guide-to-translate-your-angular-applications

Installs the Translation.io package using NPM or Yarn. This package provides the tools for synchronization and management.

```bash
# NPM
npm install @translation/angular

# Yarn
yarn add @translation/angular

```

--------------------------------

### React Application Setup with Lingui

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Set up your React application to use Lingui for internationalization, including loading and activating locales.

```javascript
import { i18n } from '@lingui/core'
import { I18nProvider } from '@lingui/react'
import { messages } from './locales/en/messages' // English catalog of translations
import Inbox from './Inbox'

i18n.load('en', messages)
i18n.activate('en')

const App = () => (
  <I18nProvider i18n={i18n}>
    <Inbox />
  </I18nProvider>
)

```

--------------------------------

### Create Source Edition

Source: https://translation.io/docs/api

This example demonstrates creating a source edition to update the source text of segments associated with a specific key. The new source text is provided.

```JSON
{
  "key": "home.call_to_action.bottom",
  "new_source": "Click here to subscribe"
}

```

--------------------------------

### Lingui Configuration (.linguirc)

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Example .linguirc configuration file specifying locales, source locale, catalog paths, and Translation.io service details.

```json
{
  "locales": ["en", "fr", "nl", "de", "es"],
  "sourceLocale": "en",
  "catalogs": [{
    "path": "src/locales/{locale}/messages",
    "include": ["src"]
  }],
  "service": {
    "name": "TranslationIO",
    "apiKey": "abcdefghijklmnopqrstuvwxyz012345"
  }
}
```

--------------------------------

### JavaScript Application Setup with Lingui

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Set up your plain JavaScript application to use Lingui for internationalization, including loading and activating locales.

```javascript
import { i18n } from '@lingui/core'
import { messages } from './locales/en/messages' // English catalog of translations

i18n.load('en', messages)
i18n.activate('en')

```

--------------------------------

### Pure Ruby Setup for Translation Gem

Source: https://translation.io/docs/guide-to-translate-your-rails-applications

This snippet shows how to set up the translation gem in a pure Ruby project by mocking Rails components and configuring the gem.

```ruby
require 'rubygems'
require 'active_support/all'
require 'yaml'

class FakeConfig
  def after_initialize
  end
  def development?
    false
  end
end

module Rails
  class Railtie
    def self.rake_tasks
      yield
    end

    def self.initializer(*args)
    end

    def self.config
      ::FakeConfig.new
    end
  end

  def self.env
    ::FakeConfig.new
  end
end

task :environment do
end

require 'translation'

I18n.load_path += Dir[File.join('i18n', '**', '*.{yml,yaml}')]

# Put your configuration here:
TranslationIO.configure do |config|
  config.yaml_locales_path = 'i18n'
  config.api_key           = ''
  config.source_locale     = 'en'
  config.target_locales    = ['nl', 'de']
  config.metadata_path     = 'i18n/.translation_io'
end

```

--------------------------------

### API Response for Segment Creation

Source: https://translation.io/docs/api

Example response structure after successfully creating a segment.

```json
{
  "segment": {
    "id": 1,
    "source_id": "8976a51c2a5a74be9bdabc07c29c10cb9e69b86c719ce071052e9b7adf25d0a7",
    "target_language": "fr",
    "type": "key",
    "key": "homepage.title",
    "source": "Welcome to the application",
    "target": "",
    "created_at": 1775314159,
    "updated_at": 1775314159
  }
}
```

```json
{
  "segment": {
    "id": 1,
    "source_id": "9f38aa51fc3131277fc4abb4dd9cd42513336745720b7f7a487be605ee5ff3c0",
    "target_language": "fr",
    "type": "source",
    "source": ":count product in the cart",
    "target": ":count produit dans le panier",
    "source_plural": ":count products in the cart",
    "target_plural": ":count articles dans le panier",
    "context": "cart",
    "comment": "Please keep ':count' as placeholder in the translations",
    "references": ["views/cart.html"],
    "created_at": 1775314159,
    "updated_at": 1775314159
  }
}
```

--------------------------------

### Translated Spanish Segment Example

Source: https://translation.io/docs/create-library

An example of a Spanish segment with its translation. It uses the 'key' type, similar to the French segment.

```json
{
  "type": "key",
  "key": "goodbye.message",
  "source": "Goodbye world",
  "target": "Adios al mundo"
}
```

--------------------------------

### API Error Response Example

Source: https://translation.io/docs/api

Illustrates the JSON format for API error responses, detailing invalid parameters.

```json
{
  "errors": [
    "Invalid 'target_language': er. Please use one of the project target languages: fr.",
    "Invalid 'type': both. Please use 'key', 'source' or 'all'."
  ]
}

```

--------------------------------

### Translated French Segment Example

Source: https://translation.io/docs/create-library

An example of a French segment with its translation. The 'type' is 'key', indicating it's a translatable string identified by a key.

```json
{
  "type": "key",
  "key": "goodbye.message",
  "source": "Goodbye world",
  "target": "Au revoir le monde"
}
```

--------------------------------

### Source YAML for I18n

Source: https://translation.io/docs/guide-to-translate-your-rails-applications

Example of a source YAML file structure for I18n translations, including keys for titles, pluralization, and interpolation.

```yaml
en:
  inbox:
    title:   'Title to be translated'
    message:
      zero:  'no messages'
      one:   'one message'
      other: '%{count} messages'
    hello:   'Hello %{name}'


```

--------------------------------

### Add Tag to Segment

Source: https://translation.io/docs/api

This example demonstrates how to add a tag to a specific segment using its ID. The tag 'need review' is applied.

```HTTP
POST https://translation.io/api/v1/segments/1/add_tag.json?api_key=<YOUR_API_KEY>

```

```JSON
{
  "name": "need review"
}

```

```JSON
{
  "segment": {
    "id": 1,
    "source_id": "85af68954641ff0400756bc3b93de505680e621e834040a63732621e659c1d82",
    "target_language": "fr",
    "type": "source",
    "source": "Hello",
    "target": "Bonjour",
    "tags": ["need review"],
    "created_at": 1775314159,
    "updated_at": 1775345678
  }
}

```

--------------------------------

### Example Request Body for segments/init

Source: https://translation.io/docs/create-library

This JSON object represents the expected request body for the 'segments/init' endpoint when providing target languages and segments. It's crucial for pushing initial translations.

```json
{
  "target_languages": ["nl"],
  "segments": {
    "fr": [],
    "nl": []
  }
}
```

--------------------------------

### Example Response for Segment Synchronization

Source: https://translation.io/docs/create-library

This JSON object represents the response from Translation.io after a segment synchronization. It includes project details and the synchronized segments.

```json
{
  "project": {
    "name": "project_name",
    "url" : "https://translation.io/owner_name/project_name"
  },
  "segments": {
    "fr": [segment_1_fr, segment_2_fr, ...],
    "es": [segment_1_es, segment_2_es, ...]
  }
}
```

--------------------------------

### Define I18n Translations in YAML

Source: https://translation.io/docs/guide-to-translate-your-rails-applications

Example structure for an `en.yml` file, defining translations for a component named 'my_component' with keys 'your_name' and 'title'.

```yaml
en:
  my_component:
    your_name: Your name
    title: Title
```

--------------------------------

### Example Request for Segment Synchronization

Source: https://translation.io/docs/create-library

This JSON object represents a request to synchronize segments with Translation.io. It specifies source and target languages and provides segments with their translations.

```json
{
  "source_language": "en",
  "target_languages": ["fr", "es"],
  "segments": {
    "fr": [segment_1_fr, segment_2_fr, ...],
    "es": [segment_1_es, segment_2_es, ...]
  }
}
```

--------------------------------

### Initialize Project and Push Translations

Source: https://translation.io/docs/guide-to-translate-your-laravel-applications

Initialize your project with Translation.io and push existing translations.

```bash
php artisan translation:init

```

--------------------------------

### Initialize Translation Project

Source: https://translation.io/docs/guide-to-translate-your-angular-applications

Initializes your project with Translation.io by pushing source keys and existing translations. Use NPM or YARN.

```bash
# NPM
npm run translation:init

# YARN
yarn translation:init

```

--------------------------------

### Initialize Library with HTTP Header Authentication

Source: https://translation.io/docs/create-library

Authenticate your library initialization request by including the project API key in the 'x-api-key' HTTP header. This is the third authentication method available for API requests.

```bash
curl -X POST https://translation.io/api/v1/segments/init.json \
  -H 'x-api-key: YOUR_API_KEY'
```

--------------------------------

### Initialize Library with URL Query Parameter Authentication

Source: https://translation.io/docs/create-library

This cURL request demonstrates how to authenticate by appending the project API key as a query parameter in the URL. This method is an alternative to using JSON parameters or HTTP headers.

```bash
curl -X POST https://translation.io/api/v1/segments/init.json?api_key=YOUR_API_KEY
```

--------------------------------

### Good Use Cases for Context in Translations

Source: https://translation.io/docs/guide-to-translate-your-angular-applications

Demonstrates how to use context and comments to create distinct source keys for identical source texts, aiding translators.

```html
<span i18n="Numbered day in a calendar|">Date</span>
<span i18n="Social meeting with someone|">Date</span>
```

```html
<span i18n="Verb|Text on a button used to report a problem">Report</span>
<span i18n="Noun|Title of the Report section in the app">Report</span>
```

--------------------------------

### Initialize Library with JSON Parameter Authentication

Source: https://translation.io/docs/create-library

Use this cURL request to initialize your library by sending the project API key within the JSON body. This is the first step in pushing existing translations to Translation.io.

```bash
curl -X POST https://translation.io/api/v1/segments/init.json \
  -H 'content-type: application/json' \
  -d '{
        "api_key": "YOUR_API_KEY"
      }'
```

--------------------------------

### Translated Spanish Segment of type 'source'

Source: https://translation.io/docs/create-library

An example of a translated segment in Spanish for a 'source' type.

```json
{
  "type": "source",
  "source": "Hello world",
  "target": "Hola mundo"
}
```

--------------------------------

### source_edits/pull

Source: https://translation.io/docs/create-library

Get source editions made on the Translation.io interface. This should ideally be called successively before segments/sync.

```APIDOC
## POST source_edits/pull

### Description
Get source editions made on the Translation.io interface. This should ideally be called successively before `segments/sync`.

### Method
POST

### Endpoint
https://translation.io/api/v1/source_edits/pull.json

### Parameters
#### Request Body
- **api_key** (string) - Required - The project API key.

### Request Example
```json
{
  "api_key": "YOUR_API_KEY"
}
```

### Response
#### Success Response (200)
Returns an object containing source editions.
  - **source_edits** (object) - An object where keys are languages and values are objects of key-source edit pairs.

#### Response Example
```json
{
  "source_edits": {
    "en": {
      "some.custom.key": "Some custom value edited"
    }
  }
}
```

#### Error Response
- **errors** (array of strings) - Description of the errors encountered during the request.
```

--------------------------------

### segments/sync

Source: https://translation.io/docs/create-library

Send new keys/strings and get new translations from Translation.io. This should ideally be called successively with source_edits/pull.

```APIDOC
## POST segments/sync

### Description
Send new keys/strings and get new translations from Translation.io. This should ideally be called successively with `source_edits/pull`.

### Method
POST

### Endpoint
https://translation.io/api/v1/segments/sync.json

### Parameters
#### Request Body
- **api_key** (string) - Required - The project API key.
- **source_language** (string) - Required - The source language of the translations.
- **segments** (object) - Required - An object where keys are target languages and values are arrays of segments.
  - **[target_language]** (array) - Required - An array of segments for the given target language.

### Request Example
```json
{
  "api_key": "YOUR_API_KEY",
  "source_language": "en",
  "segments": {
    "fr": [
      "Hello updated",
      "World updated"
    ]
  }
}
```

### Response
#### Success Response (200)
Returns an object containing new and updated translations.
  - **translations** (object) - An object where keys are target languages and values are objects of key-translation pairs.

#### Response Example
```json
{
  "translations": {
    "fr": {
      "new_key": "Nouvelle traduction"
    }
  }
}
```

#### Error Response
- **errors** (array of strings) - Description of the errors encountered during the request.
```

--------------------------------

### Initialize Translation Project

Source: https://translation.io/docs/create-library

Populates a new Translation.io project by pushing all source and translated text into the backend. This call should only be executed one time per project.

```APIDOC
## POST /api/v1/segments/init(.json)

### Description
Populates a new Translation.io project by pushing all source and translated text into the backend. This call should only be executed one time per project.

### Method
POST

### Endpoint
https://translation.io/api/v1/segments/init(.json)

### Parameters
#### Query Parameters
- **source_language** (string) - Required - Source language code (e.g., "en").
- **target_languages** (array) - Required - Array of target language codes (e.g., ["fr", "es"]).
- **segments** (hash) - Required - Hash with the language codes as keys and an array of segments as value. Keys must match `target_languages` parameter.

### Request Example
```json
{
  "source_language": "en",
  "target_languages": ["fr", "es"],
  "segments": {
    "fr": [
      {
        "type": "key",
        "key": "home.call_to_action.bottom",
        "source": "Click here to subscribe",
        "target": "Cliquez ici pour vous inscrire",
        "comment": "Homepage call-to-action (the bottom one).",
        "references": ["config/locales/fr.yml", "app/home/index.html:33"]
      },
      {
        "type": "source",
        "source": "product in the cart",
        "target": "article dans le panier",
        "source_plural": "products in the cart",
        "target_plural": "articles dans le panier",
        "context": "Order summary",
        "comment": "Order summary that is displayed next to the cart.",
        "references": ["gettext/fr/app.po", "app/home/index.html:33"]
      }
    ],
    "es": [
      {
        "type": "key",
        "key": "home.call_to_action.bottom",
        "source": "Click here to subscribe",
        "target": "Haga clic aquí para suscribirse",
        "comment": "Llamada a la acción de la página de inicio (la de abajo).",
        "references": ["config/locales/es.yml", "app/home/index.html:33"]
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **project** (hash) - Project name and URL. Example: `{"name": "project_name", "url": "https://translation.io/owner_name/project_name"}`
- **segments** (hash) - Hash with the language codes as keys and an array of segments as value. Example: see below.

#### Response Example
```json
{
  "project": {
    "name": "my_project",
    "url": "https://translation.io/my_account/my_project"
  },
  "segments": {
    "fr": [
      {
        "id": 1,
        "key": "home.call_to_action.bottom",
        "type": "key",
        "source": "Click here to subscribe",
        "target": "Cliquez ici pour vous inscrire",
        "created_at": "2023-01-01T10:00:00Z",
        "updated_at": "2023-01-01T10:00:00Z"
      },
      {
        "id": 2,
        "type": "source",
        "source": "product in the cart",
        "target": "article dans le panier",
        "source_plural": "products in the cart",
        "target_plural": "articles dans le panier",
        "context": "Order summary",
        "created_at": "2023-01-01T10:00:00Z",
        "updated_at": "2023-01-01T10:00:00Z"
      }
    ],
    "es": [
      {
        "id": 3,
        "key": "home.call_to_action.bottom",
        "type": "key",
        "source": "Click here to subscribe",
        "target": "Haga clic aquí para suscribirse",
        "created_at": "2023-01-01T10:00:00Z",
        "updated_at": "2023-01-01T10:00:00Z"
      }
    ]
  }
}
```
```

--------------------------------

### Set Locale Middleware Routes

Source: https://translation.io/docs/guide-to-translate-your-laravel-applications

Examples of applying the 'set.locale' middleware to routes in Laravel for global locale management.

```php
// in routes/web.php

// Solution 1: Apply the locale selection to root.
//             => https://yourdomain.com?locale=fr
Route::get('/', function () {
    return view('welcome');
})->middleware('set.locale');

// Solution 2: Apply the locale selection to many routes.
//             => https://yourdomain.com/...?locale=fr
Route::middleware('set.locale')->group(function () {
    Route::get('/', function () {
        return view('welcome');
    });
});

// Solution 3: prefix your routes with the locale and apply it.
//             => https://yourdomain.com/fr
//             => https://yourdomain.com/fr/...
Route::prefix('{locale?}')->middleware('set.locale')->group(function() {
    Route::get('/', function () {
        return view('welcome');
    });
});
```

--------------------------------

### Sync Translations (NPM)

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Push source keys and existing translations to Translation.io and generate minified JavaScript catalog files using NPM.

```bash
# NPM
npm run sync
```

--------------------------------

### Create New Source Edition

Source: https://translation.io/docs/api

This snippet shows the JSON payload for creating a new source edition. It includes the key and the new source string.

```json
{
  "key": "homepage.title",
  "new_source": "Welcome to this fantastic application!" // old source was "Welcome to the application"
}
```

--------------------------------

### Untranslated Spanish Segment (Source Type)

Source: https://translation.io/docs/create-library

An example of an untranslated Spanish segment of type 'source'. The 'target' field is optional when empty.

```json
{
  "type": "source",
  "source": "Hello world",
  "target": ""
}
```

--------------------------------

### Get Existing Segment

Source: https://translation.io/docs/api

Retrieves details of an existing segment by its ID. Includes source text, target text, and associated tags.

```APIDOC
## GET /api/v1/segments/:id.json

### Description
Retrieves details of an existing segment by its ID.

### Method
GET

### Endpoint
/api/v1/segments/:id.json

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API key for authentication.

### Response
#### Success Response (200)
- **segment** (hash) - Contains the segment details including id, source, target, and more.

### Response Example
```json
{
  "segment": {
    "id": 2,
    "source_id": "b9d78193f955836a4ffd2ace3d06c725f605a8fdf142522908dc5605fce30f72",
    "target_language": "fr",
    "type": "source",
    "source": "Good afternoon",
    "target": "Bon après-midi",
    "tags": [
      "proofread"
    ],
    "created_at": 1775314159,
    "updated_at": 1775345678
  }
}
```
```

--------------------------------

### Initialize Translation Project

Source: https://translation.io/docs/guide-to-translate-your-rails-applications

Initialize your translation project and push existing translations to Translation.io using the rake task.

```ruby
bundle exec rake translation:init

```

--------------------------------

### Retrieve an Existing Segment

Source: https://translation.io/docs/api

Use a GET request to fetch a specific segment by its ID. Ensure you include your API key in the request.

```http
GET https://translation.io/api/v1/segments/2.json?api_key=<YOUR_API_KEY>
```

--------------------------------

### Authenticate with HTTP Headers

Source: https://translation.io/docs/api

Authenticate by providing your API key in the 'x-api-key' header of the request.

```bash
curl -X GET https://translation.io/api/v1/segments.json \
  -H 'x-api-key: YOUR_API_KEY'

```

--------------------------------

### Retrieve a segment

Source: https://translation.io/docs/api

Fetches a specific segment by its unique identifier. Useful for getting the current translation status or details of a particular segment.

```APIDOC
## GET /segments/{id}.json

### Description
Retrieves a specific segment by its ID. This endpoint allows you to fetch the details of a single translation segment.

### Method
GET

### Endpoint
/segments/{id}.json

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the segment to retrieve.

#### Query Parameters
- **api_key** (string) - Required - Your project API key for authentication.

### Request Example
```json
{
  "api_key": "YOUR_API_KEY"
}
```

### Response
#### Success Response (200)
- **segment** (object) - The requested segment object.

#### Response Example
```json
{
  "segment": {
    "id": 1,
    "key": "welcome_message",
    "translation": {
      "en": "Welcome!",
      "fr": "Bienvenue!"
    },
    "created_at": "2023-01-01T10:00:00Z",
    "updated_at": "2023-01-01T10:00:00Z"
  }
}
```
```

--------------------------------

### Laravel Localization Syntaxes (JSON)

Source: https://translation.io/docs/guide-to-translate-your-laravel-applications

Illustrates using Laravel's `__` function with source text directly from JSON files.

```php
// Regular
__("Text to be translated");

// Pluralization
trans_choice(__('One message|Many messages'), $number);

// Interpolation
__('Hello :name', ['name' => $user->name]);

```

```json
{
    "Text to be translated": "",
    "One message|Many messages": "",
    "Hello :name": ""
}

```

```php
public function boot()
{
    $loader = $this->app['translation.loader'];

    // or 'resources/lang/my_feature' in Laravel < 9
    $loader->addJsonPath(base_path('lang/my_feature')); 
}

```

--------------------------------

### Remove Tag from Segment

Source: https://translation.io/docs/api

This example shows how to remove a tag from a segment by providing the segment ID and the tag name. The tag 'proofread' is removed.

```HTTP
POST https://translation.io/api/v1/segments/2/remove_tag.json?api_key=<YOUR_API_KEY>

```

```JSON
{
  "name": "proofread"
}

```

```JSON
{
  "segment": {
    "id": 2,
    "source_id": "b9d78193f955836a4ffd2ace3d06c725f605a8fdf142522908dc5605fce30f72",
    "target_language": "fr",
    "type": "source",
    "source": "Good afternoon",
    "target": "Bon après-midi",
    "created_at": 1775314159,
    "updated_at": 1775345678
  }
}

```

--------------------------------

### Sync Translations (Yarn)

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Push source keys and existing translations to Translation.io and generate minified JavaScript catalog files using Yarn.

```bash
# Yarn
yarn sync
```

--------------------------------

### API Request for Listing Segments with Error Conditions

Source: https://translation.io/docs/api

Example of a request payload that might trigger validation errors for target language and type.

```json
{
  "target_language": "er",
  "type": "both"
}

```

--------------------------------

### Authenticate with URL Query Parameter

Source: https://translation.io/docs/api

Authenticate by appending your API key as a query parameter to the request URL.

```bash
curl -X GET https://translation.io/api/v1/segments.json?api_key=YOUR_API_KEY

```

--------------------------------

### Sync and Show Purgeable Keys

Source: https://translation.io/docs/guide-to-translate-your-laravel-applications

Synchronize translations and identify unused keys/strings based on the current branch.

```bash
php artisan translation:sync_and_show_purgeable

```

--------------------------------

### Detect User Locale with @lingui/detect-locale

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Shows how to use the @lingui/detect-locale package to automatically detect the user's locale from various sources like URL, storage, or navigator. Includes a default fallback.

```javascript
import { detect, fromUrl, fromStorage, fromNavigator } from "@lingui/detect-locale"

// can be a function with custom logic or just a string, `detect` method will handle it
const DEFAULT_FALLBACK = () => "en"

const result = detect(
  fromUrl("lang"),
  fromStorage("lang"),
  fromNavigator(),
  DEFAULT_FALLBACK
)

console.log(result) // "en"
```

--------------------------------

### GetText Translation Functions

Source: https://translation.io/docs/guide-to-translate-your-laravel-applications

Demonstrates the basic GetText functions for translation, pluralization, and context.

```php
// Regular
t("Text to be translated");

// Pluralization
n("Singular text", "Plural text", $number);

// Regular with context
p("context", "Text to be translated");

// Pluralization with context
np("context", "Singular text", "Plural text", $number);

// Simple Interpolations (works with n, p and np too)
t('Hello %s', $user->name);

// Complex Interpolations (works with n, p and np too)
t(':city1 is bigger than :city2', [ ':city1' => 'NYC', ':city2' => 'BXL' ]);
```

--------------------------------

### Configure Proxy Settings

Source: https://translation.io/docs/guide-to-translate-your-angular-applications

Add proxy configuration to your `tio.config.json` file if you need to connect to Translation.io through a proxy server.

```json
{
  "proxy": "http://login:pass@127.0.0.1:8080"
}
```

--------------------------------

### Project Information in Response

Source: https://translation.io/docs/create-library

This JSON snippet shows the project details returned in the synchronization response, including the project name and its URL.

```json
{
  "name": "project_name",
  "url": "https://translation.io/owner_name/project_name"
}
```

--------------------------------

### Update an Existing Source Segment

Source: https://translation.io/docs/api

Use a PATCH request to update an existing source segment. This example shows updating the target text for a source segment. The API key is required.

```http
// PATCH https://translation.io/api/v1/segments/1.json?api_key=<YOUR_API_KEY>

{
  "target": "Bonjour!"
}
```

--------------------------------

### Laravel Localization Syntaxes (PHP)

Source: https://translation.io/docs/guide-to-translate-your-laravel-applications

Demonstrates the use of Laravel's default localization functions with PHP arrays for translations.

```php
// Regular
__('inbox.title');

// Regular with sublevel key
__('inbox.menu.title');

// Pluralization
trans_choice('inbox.messages', $number);

// Interpolation
__('inbox.hello', ['name' => $user->name]);

```

```php
<?php
return [
    'title' => 'Title to be translated',
    'hello' => 'Hello :name',
    'messages' => 'One message|Many messages',
    'menu' => [
        'title' => 'Title of menu'
    ]
];

```

--------------------------------

### Publish Configuration File

Source: https://translation.io/docs/guide-to-translate-your-laravel-applications

Publish the configuration file to your Laravel application or create it manually.

```php
<?php
return [
    'key' => env('TRANSLATIONIO_KEY'),
    'source_locale' => 'en',
    'target_locales' => ['fr', 'nl', 'de', 'es']
];

```

--------------------------------

### Configure Custom Source File Path

Source: https://translation.io/docs/guide-to-translate-your-angular-applications

Specify a custom path for your source locale file (XLF) in `tio.config.json` if it deviates from the default.

```json
{
  "source_file_path" : "src/translations/sources.xlf"
}
```

--------------------------------

### Sync Translations with Translation.io

Source: https://translation.io/docs/guide-to-translate-your-angular-applications

Synchronizes new translatable source keys and retrieves translations from Translation.io. Use NPM or YARN.

```bash
# NPM
npm run translation:sync

# YARN
yarn translation:sync

```

--------------------------------

### Create a source edition

Source: https://translation.io/docs/api

Creates a new source edition for a project. This is typically used when updating source files and needing to synchronize changes.

```APIDOC
## POST /source_editions.json

### Description
Creates a new source edition. This is typically used after updating source files to signal Translation.io to re-process them and update segments.

### Method
POST

### Endpoint
/source_editions.json

### Parameters
#### Request Body
- **api_key** (string) - Required - Your project API key for authentication.
- **source_edition** (object) - Required - Contains information about the source edition.
  - **locale** (string) - Required - The locale code of the source files (e.g., 'en').
  - **file_format** (string) - Required - The format of the source files (e.g., 'yml', 'json', 'po').
  - **file_path** (string) - Required - The path to the source file within your project.

### Request Example
```json
{
  "api_key": "YOUR_API_KEY",
  "source_edition": {
    "locale": "en",
    "file_format": "yml",
    "file_path": "config/locales/en.yml"
  }
}
```

### Response
#### Success Response (201)
- **source_edition** (object) - The details of the created source edition.

#### Response Example
```json
{
  "source_edition": {
    "id": 50,
    "locale": "en",
    "file_format": "yml",
    "file_path": "config/locales/en.yml",
    "created_at": "2023-01-03T12:00:00Z"
  }
}
```
```

--------------------------------

### Publish Language Files (Laravel 9+)

Source: https://translation.io/docs/guide-to-translate-your-laravel-applications

If using Laravel 9 or later, publish the default language files if they are not present.

```bash
php artisan lang:publish

```

--------------------------------

### segments/init

Source: https://translation.io/docs/create-library

Push existing translations to Translation.io. This endpoint should only be called once after project configuration.

```APIDOC
## POST segments/init

### Description
Push existing translations to Translation.io. This endpoint should only be called once after project configuration. Subsequent calls will be denied.

### Method
POST

### Endpoint
https://translation.io/api/v1/segments/init.json

### Parameters
#### Request Body
- **api_key** (string) - Required - The project API key.
- **source_language** (string) - Required - The source language of the translations.
- **segments** (object) - Required - An object where keys are target languages and values are arrays of segments.
  - **[target_language]** (array) - Required - An array of segments for the given target language.

### Request Example
```json
{
  "api_key": "YOUR_API_KEY",
  "source_language": "en",
  "segments": {
    "fr": [
      "Hello",
      "World"
    ],
    "nl": [
      "Hallo",
      "Wereld"
    ]
  }
}
```

### Response
#### Success Response (200)
Returns an empty JSON object `{}` on success.

#### Response Example
```json
{}
```

#### Error Response
- **errors** (array of strings) - Description of the errors encountered during the request.
```

--------------------------------

### Create Source Edition

Source: https://translation.io/docs/api

Allows you to create a new source edition for a given key. This is useful for updating existing translations when the source text changes.

```APIDOC
## POST /sources/editions

### Description
Creates a new source edition for a specified key, updating the source text and triggering re-translation or flagging for existing translations.

### Method
POST

### Endpoint
/sources/editions

### Parameters
#### Request Body
- **key** (string) - Required - The unique identifier for the translation key.
- **new_source** (string) - Required - The new source text for the translation key.

### Request Example
{
  "key": "homepage.title",
  "new_source": "Welcome to this fantastic application!"
}

### Response
#### Success Response (200)
- **segments** (array) - A list of translation segments affected by the source edition.
  - **id** (integer) - The unique identifier for the segment.
  - **source_id** (string) - The identifier for the source text.
  - **target_language** (string) - The language code of the target translation.
  - **type** (string) - The type of the segment (e.g., 'key').
  - **key** (string) - The translation key.
  - **source** (string) - The updated source text.
  - **target** (string) - The current target translation text.
  - **tags** (array of strings) - Tags associated with the segment, such as 'source changed'.
  - **created_at** (integer) - Timestamp when the segment was created.
  - **updated_at** (integer) - Timestamp when the segment was last updated.

#### Response Example
{
  "segments": [
    {
      "id": 1,
      "source_id": "8976a51c2a5a74be9bdabc07c29c10cb9e69b86c719ce071052e9b7adf25d0a7",
      "target_language": "fr",
      "type": "key",
      "key": "homepage.title",
      "source": "Welcome to this fantastic application!",
      "target": "Bienvenue dans cette application",
      "tags": [
        "source changed"
      ],
      "created_at": 1775314159,
      "updated_at": 1775345678
    }
  ]
}
```

--------------------------------

### Change Current Locale with Lingui

Source: https://translation.io/docs/guide-to-translate-your-lingui-applications

Demonstrates how to load and activate a locale using the Lingui core library. Ensure you have the messages imported from your locale files.

```javascript
import { i18n } from '@lingui/core'
import { messages } from './locales/en/messages.js'

// [...]
i18n.load('en', messages)
i18n.activate('en')
```

--------------------------------

### Authenticate with JSON Parameter

Source: https://translation.io/docs/api

Use this method to authenticate by including your API key in the JSON body of the request.

```bash
curl -X GET https://translation.io/api/v1/segments.json \
  -H 'Content-Type: application/json' \
  -d '{
        "api_key": "YOUR_API_KEY"
      }'

```