Skip to content

Commit

Permalink
Updated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@adam-pawelek
adam-pawelek committed Jan 29, 2025
1 parent 408d622 commit ddf493f
Show file tree
Hide file tree
Showing 6 changed files with 101 additions and 689 deletions.
73 changes: 0 additions & 73 deletions docs/docs/Tutorial/Choosing OpenAI Model for Translation.md
View file
Original file line number Diff line number Diff line change
@@ -1,73 +0,0 @@
## Choosing OpenAI Model for Translation

When using the `TranslatorOpenAI` class for translation tasks, you have two options to specify the model:

1. Provide the model name as a string.
2. Use the `ModelForTranslator` enum to select from predefined models.

### Option 1: Using Model Name as a String

You can directly pass the model name as a string when creating an instance of `TranslatorOpenAI`.

```python
from llmtranslate import TranslatorOpenAI

# Example with a model name as a string
translator = TranslatorOpenAI(
api_key="YOUR_OPENAI_API_KEY",
model="gpt-4o-mini"
)

translated_text = translator.translate(
text="Cześć jak się masz? Meu nome é Adam",
to_language="en"
)
print(translated_text)
```

### Option 2: Using the `ModelForTranslator` Enum

Alternatively, you can use the `ModelForTranslator` enum to select a model. This enum contains predefined models that have been tested and come with specific versions.

```python
from llmtranslate import TranslatorOpenAI
from llmtranslate import ModelForTranslator

# Example using the ModelForTranslator enum
translator = TranslatorOpenAI(
api_key="YOUR_OPENAI_API_KEY",
model=ModelForTranslator.GPT_4o_mini
)

translated_text = translator.translate(
text="Cześć jak się masz? Meu nome é Adam",
to_language="en"
)
print(translated_text)
```

### Available Models in `ModelForTranslator` Enum

```python
from enum import Enum

class ModelForTranslator(Enum):
BEST_BIG_MODEL = "gpt-4o"
BEST_SMALL_MODEL = "gpt-4o-mini"
GPT_4o = "gpt-4o"
GPT_4o_mini = "gpt-4o-mini"
```

- **BEST_BIG_MODEL**: `"gpt-4o"` - Represents the best large model available.
- **BEST_SMALL_MODEL**: `"gpt-4o-mini"` - Represents the best smaller model, optimized for speed.
- **GPT_4o**: `"gpt-4o"` - Specific version of GPT-4o.
- **GPT_4o_mini**: `"gpt-4o-mini"` - A smaller version of GPT-4o.



### Summary

- **Flexibility**: Choose between using a string or the enum based on your preference.
- **Predefined Models**: The `ModelForTranslator` enum provides a convenient way to select tested models with known performance characteristics.


177 changes: 0 additions & 177 deletions docs/docs/Tutorial/Quick Start Guide.md
View file
Original file line number Diff line number Diff line change
@@ -1,177 +0,0 @@
# Quick Start Guide

## Installation

You can install the llmtranslate library from PyPI:

```bash
pip install llmtranslate
```

## Usage

### Setting the OpenAI API Key

Before using llmtranslate with OpenAI, you need to set your OpenAI API key. You can do this by creating an instance of the TranslatorOpenAI class.

```python
from llmtranslate import TranslatorOpenAI

# Set your OpenAI API key
translator = TranslatorOpenAI(api_key="YOUR_OPENAI_API_KEY", model="gpt-4o-mini")

```

### Language Detection

To detect the language of a given text:

```python
from llmtranslate import TranslatorOpenAI

# Set your OpenAI API key
translator = TranslatorOpenAI(api_key="YOUR_OPENAI_API_KEY", model="gpt-4o-mini")

# Detect language
detected_language = translator.get_text_language("Hello world")
if detected_language is not None:
print(detected_language.ISO_639_1_code) # Output: 'en'
print(detected_language.ISO_639_2_code) # Output: 'eng'
print(detected_language.ISO_639_3_code) # Output: 'eng'
print(detected_language.language_name) # Output: 'English'

```

!!! warning
If the translator does not detect any language, it will return None.<br>
Before using results of translator detection you should check if it returned correct result or None

### Translation

To translate text containing multiple languages into another language, you need to provide the ISO 639 language code for the target language. For a list of all ISO 639 language codes, you can refer to this [ISO 639-1 code list website](https://localizely.com/iso-639-1-list/).

```python
from llmtranslate import TranslatorOpenAI

# Set your OpenAI API key
translator = TranslatorOpenAI(api_key="YOUR_OPENAI_API_KEY", model="gpt-4o-mini")

# Translate text
translated_text = translator.translate(
text="Cześć jak się masz? Meu nome é Adam",
to_language="en" # Use ISO 639-1 code for the target language
)
print(translated_text) # Output: "Hello how are you? My name is Adam"
```


### Full Example

Here is a complete example demonstrating how to use the library:

```python
from llmtranslate import TranslatorOpenAI

# Initialize the translator with your OpenAI API key
translator = TranslatorOpenAI(api_key="YOUR_OPENAI_API_KEY", model="gpt-4o-mini")

# Detect language
detected_language = translator.get_text_language("jak ty się nazywasz")
if detected_language is not None:
print(detected_language.ISO_639_1_code) # Output: 'pl'
print(detected_language.ISO_639_2_code) # Output: 'pol'
print(detected_language.ISO_639_3_code) # Output: 'pol'
print(detected_language.language_name) # Output 'Polish'

# Translate text
translated_text = translator.translate(
text="Cześć jak się masz? Meu nome é Adam",
to_language="en"
)
print(translated_text) # Output: "Hello how are you? My name is Adam"

```

### Available OpenAI Models for Translation
The llmtranslate library provides access to various OpenAI models for translation. Below are the supported models and their use cases:

```python
from llmtranslate import TranslatorOpenAI

# Recommended for precise translation, high-precision model
translator = TranslatorOpenAI(api_key="YOUR_OPENAI_API_KEY", model="gpt-4o")

# A budget-friendly option, balancing cost and quality
translator = TranslatorOpenAI(api_key="YOUR_OPENAI_API_KEY", model="gpt-4o-mini")

```


## Using Asynchronous Methods

The `llmtranslate` library provides asynchronous methods to allow you to perform language detection and translation tasks efficiently in an async environment. If your application uses `asyncio` or another asynchronous framework, you can take full advantage of these async methods to avoid blocking your program while waiting for language detection or translation tasks to complete.

### Example of Using Asynchronous Methods

The following example demonstrates how to use the `async_get_text_language` and `async_translate_text` methods:

```python
import asyncio
from llmtranslate import TranslatorOpenAI

# Initialize the translator with your OpenAI API key
translator = TranslatorOpenAI(api_key="YOUR_OPENAI_API_KEY", model="gpt-4o-mini")


# Async function to detect language and translate text
async def detect_and_translate():
# Detect language asynchronously
detected_language = await translator.async_get_text_language("Hola, ¿cómo estás?")
if detected_language is not None:
print(detected_language.ISO_639_1_code) # Output: 'es'
print(detected_language.language_name) # Output: 'Spanish'

# Translate text asynchronously
translated_text = await translator.async_translate(
text="Cześć jak się masz? Meu nome é Adam",
to_language="en" # Use ISO 639-1 code for the target language
)
print(translated_text) # Output: "Hello how are you? My name is Adam"


# Run the async function
asyncio.run(detect_and_translate())
```

### Key Asynchronous Methods

1. **`async_get_text_language(text: str)`**:
This method detects the language of the provided text asynchronously.
- **Parameters**:
- `text`: The input text whose language needs to be detected.
- **Returns**: A `TextLanguage` object containing the detected language's ISO 639-1, ISO 639-2, ISO 639-3 codes, and the language name.

**Example**:
```python
detected_language = await translator.async_get_text_language("Hallo, wie geht's?")
```

2. **`async_translate_text(text: str, to_language: str)`**:
This method translates the input text asynchronously to the specified target language.
- **Parameters**:
- `text`: The input text to be translated.
- `to_language`: The target language in ISO 639-1 code.
- **Returns**: A string containing the translated text.

**Example**:
```python
translated_text = await translator.async_translate("Bonjour tout le monde", "en")
```

### Why Use Asynchronous Methods?

Using asynchronous methods allows your application to handle multiple tasks concurrently, improving efficiency, especially when dealing with large amounts of text or performing multiple translations simultaneously. This non-blocking behavior is ideal for web services, APIs, and any scenario requiring high responsiveness.

### Running Asynchronous Functions

Remember that asynchronous methods must be called within an `async` function. To execute them, you can use `asyncio.run()` as shown in the examples above.
115 changes: 0 additions & 115 deletions docs/docs/Tutorial/TranslatorMistralCloud.md
View file
Original file line number Diff line number Diff line change
@@ -1,115 +0,0 @@

# TranslatorMistralCloud Class Documentation

The `TranslatorMistralCloud` class is fully compatible with both `TranslatorOpenSourceLLM` and `TranslatorOpenAI` classes. It contains all their methods and uses models hosted on the Mistral cloud for translation, language detection, and other tasks, providing the same functionality with cloud-based execution.


## How to Use

### Initialization

To use the `TranslatorMistralCloud` class, initialize it with your Mistral API key. Optionally, you can specify a model, with `MISTRAL_LARGE` as the default.

```python
from llmtranslate import TranslatorMistralCloud, ModelForTranslator

translator = TranslatorMistralCloud(
api_key="your_api_key_here",
model="open-mistral-nemo"
)
```

### Choose Mistral model
The `TranslatorMistralCloud` class allows you to choose a translation model when initializing. By default, it uses `MISTRAL_LARGE`, but you can specify other models using the `ModelForTranslator` enum or as a string.

**Example using Enum:**
```python
from llmtranslate import TranslatorMistralCloud, ModelForTranslator

translator = TranslatorMistralCloud(
api_key="your_api_key_here",
model=ModelForTranslator.MISTRAL_NEMO
)
```

**Example using String**
```python
from llmtranslate import TranslatorMistralCloud, ModelForTranslator

translator = TranslatorMistralCloud(
api_key="your_api_key_here",
model="open-mistral-nemo"
)

```




### Translate


Translates the provided text into the specified language using the ISO 639-1 code.

- **Parameters:**
- `text`: The text to translate.
- `to_language`: Target language (default is English: `"eng"`).


```python
from llmtranslate import TranslatorMistralCloud
translator = TranslatorMistralCloud(
api_key="your_api_key_here",
model="open-mistral-nemo"
)
translated_text = translator.translate("Bonjour", "en")
print(translated_text) # Output: Hello
```

### Detect language

Detects the language of the given text and returns its ISO 639-1 code.


```python
from llmtranslate import TranslatorMistralCloud
translator = TranslatorMistralCloud(
api_key="your_api_key_here",
model="open-mistral-nemo"
)
detected_language = translator.get_text_language("jak ty się nazywasz")
if detected_language is not None:
print(detected_language.ISO_639_1_code) # Output: 'pl'
print(detected_language.ISO_639_2_code) # Output: 'pol'
print(detected_language.ISO_639_3_code) # Output: 'pol'
print(detected_language.language_name) # Output 'Polish'
```

!!! warning
If the translator does not detect any language, it will return None.<br>
Before using results of translator detection you should check if it returned correct result or None



## Example Usage

```python
from llmtranslate import TranslatorMistralCloud
translator = TranslatorMistralCloud(
api_key="your_api_key_here",
model="open-mistral-nemo"
)

# Translate text to English
translated_text = translator.translate("こんにちは", "en")
print(translated_text) # Output: Hello

# Detect language
detected_language = translator.get_text_language("jak ty się nazywasz")
if detected_language is not None:
print(detected_language.ISO_639_1_code) # Output: 'pl'
print(detected_language.ISO_639_2_code) # Output: 'pol'
print(detected_language.ISO_639_3_code) # Output: 'pol'
print(detected_language.language_name) # Output 'Polish'

```
Loading

0 comments on commit ddf493f

Please sign in to comment.