> For the complete documentation index, see [llms.txt](https://ptkyoku.gitbook.io/localflow-translate-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ptkyoku.gitbook.io/localflow-translate-docs/api-reference/usage-guide.md).

# Usage Guide

Learn how to check usage, load glossaries, and translate text with DeepLService.

## Usage guide

Use `DeepLService` to check usage, load glossaries, and translate text.

All methods are asynchronous. Await each call and check `statusCode` before reading results.

{% hint style="info" %}
Provide a valid DeepL API key for every request. Pass `null` as `glossaryName` when no glossary is needed.
{% endhint %}

### Check API usage

Retrieve the current DeepL API character usage.

```csharp
var result = await DeepLService.GetUsage(apiKey, null);
if (result.statusCode != DeepLStatusCode.Success)
    return;

Debug.Log($"Usage: {result.characterCount} / {result.characterLimit}");
```

### Load glossaries

Load the glossaries available in the DeepL account before using one by name.

```csharp
var result = await DeepLService.GetGlossary(apiKey, null);
if (result.statusCode != DeepLStatusCode.Success)
    return;
```

{% hint style="info" %}
Use `GetGlossaryNames()` to list loaded glossary names.
{% endhint %}

### Translate text

Choose an overload based on the number of texts and target languages.

#### Single text

Translate one text into one target language.

```csharp
var response = await DeepLService.Translate(apiKey, sourceCode, targetCode, text, glossaryName, null);
if (response.statusCode != DeepLStatusCode.Success)
    return;

var translatedText = response.Items[0].Texts[0];
```

#### Multiple texts

Translate multiple texts into one target language. The result order matches the input order.

```csharp
var response = await DeepLService.Translate(
    apiKey,
    sourceCode,
    targetCode,
    texts,
    glossaryName,
    null);
if (response.statusCode != DeepLStatusCode.Success)
    return;

var item = response.Items[0];
for (int i = 0; i < item.Texts.Count; i++)
{
    var key = keys[i].key;
    var translatedText = item.Texts[i];
}
```

#### Multiple target languages

Translate multiple texts into several target languages. Each `TranslateResultItem` represents one target language.

```csharp
var response = await DeepLService.Translate(
    apiKey,
    sourceCode,
    targetCodes,
    texts,
    glossaryName,
    null);
if (response.statusCode != DeepLStatusCode.Success)
    return;

foreach (var item in response.Items)
{
    for (int i = 0; i < item.Texts.Count; i++)
    {
        var key = keys[i].key;
        var translatedText = item.Texts[i];
    }
}
```

### Handle errors

All API methods return a `DeepLStatusCode`. Check it before using returned data.

```csharp
if (response.statusCode != DeepLStatusCode.Success)
{
    Debug.LogError(response.errorMessage);
    return;
}
```

### Track progress

All asynchronous methods accept an optional progress callback.

```csharp
var response = await DeepLService.Translate(
    apiKey,
    sourceCode,
    targetCode,
    texts,
    glossaryName,
    (language, progress) =>
    {
        Debug.Log($"{language}: {progress:P0}");
    });
```

`GetUsage` and `GetGlossary` use an `Action<float>` callback.

```csharp
var result = await DeepLService.GetUsage(
    apiKey,
    progress => Debug.Log(progress));
```