Skip to content

Commit 6193a4a

Browse files
bogdankosticanakin87
bogdankostic
and
anakin87
authored
docs: add LaraDocumentTranslator documentation (#10723)
* docs: add LaraDocumentTranslator documentation * docs: update LaraDocumentTranslator documentation for consistency in terminology * Apply suggestions from code review Co-authored-by: Stefano Fiorucci <stefanofiorucci@gmail.com> --------- Co-authored-by: Stefano Fiorucci <stefanofiorucci@gmail.com>
1 parent 1da3ef4 commit 6193a4a

4 files changed

Lines changed: 236 additions & 0 deletions

File tree

‎docs-website/docs/pipeline-components/translators/laradocumenttranslator.mdx‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: "LaraDocumentTranslator"
3+
id: laradocumenttranslator
4+
slug: "/laradocumenttranslator"
5+
description: "This component translates the text content of Haystack documents using the Lara translation API."
6+
---
7+
8+
# LaraDocumentTranslator
9+
10+
This component translates the text content of Haystack documents using the Lara translation API.
11+
12+
<div className="key-value-table">
13+
14+
| | |
15+
| --- | --- |
16+
| **Most common position in a pipeline** | After any component that produces documents, such as a Retriever or a Converter |
17+
| **Mandatory init variables** | `access_key_id`: Lara API access key ID. Can be set with `LARA_ACCESS_KEY_ID` env var. <br /> <br />`access_key_secret`: Lara API access key secret. Can be set with `LARA_ACCESS_KEY_SECRET` env var. |
18+
| **Mandatory run variables** | `documents`: A list of documents to be translated |
19+
| **Output variables** | `documents`: A list of translated documents |
20+
| **API reference** | [Lara](/reference/integrations-lara) |
21+
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/lara |
22+
23+
</div>
24+
25+
## Overview
26+
27+
[Lara](https://developers.laratranslate.com/docs/introduction) is an adaptive translation AI by [translated](https://translated.com/) that combines the fluency and context handling of LLMs with low hallucination and latency. It adapts to domains at inference time using optional context, instructions, translation memories, and glossaries.
28+
29+
`LaraDocumentTranslator` takes a list of Haystack documents, translates their text content via the Lara API, and returns new documents containing the translations. The original document ID is preserved in each translated document's metadata under the `original_document_id` key.
30+
31+
Key features:
32+
33+
- **Automatic language detection**: set `source_lang` to `None` and Lara auto-detects it.
34+
- **Translation styles**: choose `"faithful"`, `"fluid"`, or `"creative"` to control the tone.
35+
- **Context and instructions**: pass surrounding text or natural-language instructions to improve quality.
36+
- **Translation memories and glossaries**: supply memory or glossary IDs so Lara enforces consistent terminology.
37+
- **Reasoning (Lara Think)**: enable multi-step linguistic analysis for higher-quality output.
38+
39+
## Usage
40+
### Installation
41+
42+
To start using this integration with Haystack, install it with:
43+
44+
```shell
45+
pip install lara-haystack
46+
```
47+
48+
`LaraDocumentTranslator` needs Lara API credentials to work. It uses the `LARA_ACCESS_KEY_ID` and `LARA_ACCESS_KEY_SECRET` environment variables by default. Otherwise, you can pass them at initialization:
49+
50+
```python
51+
from haystack.utils import Secret
52+
from haystack_integrations.components.translators.lara import LaraDocumentTranslator
53+
54+
translator = LaraDocumentTranslator(
55+
access_key_id=Secret.from_token("<your-access-key-id>"),
56+
access_key_secret=Secret.from_token("<your-access-key-secret>"),
57+
source_lang="en-US",
58+
target_lang="de-DE",
59+
)
60+
```
61+
62+
To get your Lara API credentials, sign up at [laratranslate.com](https://laratranslate.com/).
63+
### On its own
64+
65+
Remember to set the `LARA_ACCESS_KEY_ID` and `LARA_ACCESS_KEY_SECRET` environment variables or pass them in directly.
66+
67+
```python
68+
from haystack import Document
69+
from haystack.utils import Secret
70+
from haystack_integrations.components.translators.lara import LaraDocumentTranslator
71+
72+
translator = LaraDocumentTranslator(
73+
access_key_id=Secret.from_env_var("LARA_ACCESS_KEY_ID"),
74+
access_key_secret=Secret.from_env_var("LARA_ACCESS_KEY_SECRET"),
75+
source_lang="en-US",
76+
target_lang="de-DE",
77+
)
78+
79+
doc = Document(content="Hello, world!")
80+
result = translator.run(documents=[doc])
81+
print(result["documents"][0].content)
82+
# >> "Hallo, Welt!"
83+
```
84+
85+
### In a pipeline
86+
87+
Below is an example of the `LaraDocumentTranslator` in a pipeline that fetches a webpage, converts it to a document, and translates it from English to German.
88+
89+
```python
90+
from haystack import Pipeline
91+
from haystack.components.converters import HTMLToDocument
92+
from haystack.components.fetchers import LinkContentFetcher
93+
from haystack_integrations.components.translators.lara import LaraDocumentTranslator
94+
95+
fetcher = LinkContentFetcher()
96+
converter = HTMLToDocument()
97+
translator = LaraDocumentTranslator(source_lang="en-US", target_lang="de-DE")
98+
99+
pipe = Pipeline()
100+
pipe.add_component("fetcher", fetcher)
101+
pipe.add_component("converter", converter)
102+
pipe.add_component("translator", translator)
103+
104+
pipe.connect("fetcher", "converter")
105+
pipe.connect("converter", "translator")
106+
107+
result = pipe.run(data={"fetcher": {"urls": ["https://haystack.deepset.ai/"]}})
108+
translated_docs = result["translator"]["documents"]
109+
for doc in translated_docs:
110+
print(doc.content)
111+
```

‎docs-website/sidebars.js‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -581,6 +581,13 @@ export default {
581581
'pipeline-components/tools/toolinvoker',
582582
],
583583
},
584+
{
585+
type: 'category',
586+
label: 'Translators',
587+
items: [
588+
'pipeline-components/translators/laradocumenttranslator',
589+
],
590+
},
584591
{
585592
type: 'category',
586593
label: 'Validators',

‎docs-website/versioned_docs/version-2.25/pipeline-components/translators/laradocumenttranslator.mdx‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: "LaraDocumentTranslator"
3+
id: laradocumenttranslator
4+
slug: "/laradocumenttranslator"
5+
description: "This component translates the text content of Haystack documents using the Lara translation API."
6+
---
7+
8+
# LaraDocumentTranslator
9+
10+
This component translates the text content of Haystack documents using the Lara translation API.
11+
12+
<div className="key-value-table">
13+
14+
| | |
15+
| --- | --- |
16+
| **Most common position in a pipeline** | After any component that produces documents, such as a Retriever or a Converter |
17+
| **Mandatory init variables** | `access_key_id`: Lara API access key ID. Can be set with `LARA_ACCESS_KEY_ID` env var. <br /> <br />`access_key_secret`: Lara API access key secret. Can be set with `LARA_ACCESS_KEY_SECRET` env var. |
18+
| **Mandatory run variables** | `documents`: A list of documents to be translated |
19+
| **Output variables** | `documents`: A list of translated documents |
20+
| **API reference** | [Lara](/reference/integrations-lara) |
21+
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/lara |
22+
23+
</div>
24+
25+
## Overview
26+
27+
[Lara](https://developers.laratranslate.com/docs/introduction) is an adaptive translation AI by [translated](https://translated.com/) that combines the fluency and context handling of LLMs with low hallucination and latency. It adapts to domains at inference time using optional context, instructions, translation memories, and glossaries.
28+
29+
`LaraDocumentTranslator` takes a list of Haystack documents, translates their text content via the Lara API, and returns new documents containing the translations. The original document ID is preserved in each translated document's metadata under the `original_document_id` key.
30+
31+
Key features:
32+
33+
- **Automatic language detection**: set `source_lang` to `None` and Lara auto-detects it.
34+
- **Translation styles**: choose `"faithful"`, `"fluid"`, or `"creative"` to control the tone.
35+
- **Context and instructions**: pass surrounding text or natural-language instructions to improve quality.
36+
- **Translation memories and glossaries**: supply memory or glossary IDs so Lara enforces consistent terminology.
37+
- **Reasoning (Lara Think)**: enable multi-step linguistic analysis for higher-quality output.
38+
39+
## Usage
40+
### Installation
41+
42+
To start using this integration with Haystack, install it with:
43+
44+
```shell
45+
pip install lara-haystack
46+
```
47+
48+
`LaraDocumentTranslator` needs Lara API credentials to work. It uses the `LARA_ACCESS_KEY_ID` and `LARA_ACCESS_KEY_SECRET` environment variables by default. Otherwise, you can pass them at initialization:
49+
50+
```python
51+
from haystack.utils import Secret
52+
from haystack_integrations.components.translators.lara import LaraDocumentTranslator
53+
54+
translator = LaraDocumentTranslator(
55+
access_key_id=Secret.from_token("<your-access-key-id>"),
56+
access_key_secret=Secret.from_token("<your-access-key-secret>"),
57+
source_lang="en-US",
58+
target_lang="de-DE",
59+
)
60+
```
61+
62+
To get your Lara API credentials, sign up at [laratranslate.com](https://laratranslate.com/).
63+
### On its own
64+
65+
Remember to set the `LARA_ACCESS_KEY_ID` and `LARA_ACCESS_KEY_SECRET` environment variables or pass them in directly.
66+
67+
```python
68+
from haystack import Document
69+
from haystack.utils import Secret
70+
from haystack_integrations.components.translators.lara import LaraDocumentTranslator
71+
72+
translator = LaraDocumentTranslator(
73+
access_key_id=Secret.from_env_var("LARA_ACCESS_KEY_ID"),
74+
access_key_secret=Secret.from_env_var("LARA_ACCESS_KEY_SECRET"),
75+
source_lang="en-US",
76+
target_lang="de-DE",
77+
)
78+
79+
doc = Document(content="Hello, world!")
80+
result = translator.run(documents=[doc])
81+
print(result["documents"][0].content)
82+
# >> "Hallo, Welt!"
83+
```
84+
85+
### In a pipeline
86+
87+
Below is an example of the `LaraDocumentTranslator` in a pipeline that fetches a webpage, converts it to a document, and translates it from English to German.
88+
89+
```python
90+
from haystack import Pipeline
91+
from haystack.components.converters import HTMLToDocument
92+
from haystack.components.fetchers import LinkContentFetcher
93+
from haystack_integrations.components.translators.lara import LaraDocumentTranslator
94+
95+
fetcher = LinkContentFetcher()
96+
converter = HTMLToDocument()
97+
translator = LaraDocumentTranslator(source_lang="en-US", target_lang="de-DE")
98+
99+
pipe = Pipeline()
100+
pipe.add_component("fetcher", fetcher)
101+
pipe.add_component("converter", converter)
102+
pipe.add_component("translator", translator)
103+
104+
pipe.connect("fetcher", "converter")
105+
pipe.connect("converter", "translator")
106+
107+
result = pipe.run(data={"fetcher": {"urls": ["https://haystack.deepset.ai/"]}})
108+
translated_docs = result["translator"]["documents"]
109+
for doc in translated_docs:
110+
print(doc.content)
111+
```

‎docs-website/versioned_sidebars/version-2.25-sidebars.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -575,6 +575,13 @@
575575
"pipeline-components/tools/toolinvoker"
576576
]
577577
},
578+
{
579+
"type": "category",
580+
"label": "Translators",
581+
"items": [
582+
"pipeline-components/translators/laradocumenttranslator"
583+
]
584+
},
578585
{
579586
"type": "category",
580587
"label": "Validators",

0 commit comments

Comments
 (0)