nl-processing 0.5.0__tar.gz → 1.0.2__tar.gz

nl_processing-1.0.2/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: nl_processing
+Version: 1.0.2
+Summary: Aggregate build for the nl_processing multi-package repository
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: langchain-core<1,>=0.3
+Requires-Dist: langchain-openai<1,>=0.3
+Requires-Dist: numpy<3,>=2.0
+Requires-Dist: opencv-python<5,>=4.10
+Requires-Dist: asyncpg<1,>=0.30
+Requires-Dist: aiosqlite<1,>=0.20
+
+# nl_processing
+
+[![PyPI](https://img.shields.io/pypi/v/nl_processing)](https://pypi.org/project/nl_processing/)
+
+Dutch language processing toolkit organized as a multi-package Python repository.
+
+## Install
+
+```bash
+pip install nl_processing
+```
+
+The published `nl_processing` package is the aggregate build from the repo root. Day-to-day development happens inside the package folders under `packages/`.
+
+## Repository Layout
+
+```text
+packages/
+  core/
+  extract_text_from_image/
+  extract_words_from_text/
+  translate_text/
+  translate_word/
+  database/
+  database_cache/
+  sampling/
+docs/
+pyproject.toml        # aggregate build for the published nl_processing package
+Makefile              # repo-wide lint/test entrypoint
+```
+
+Each package has its own:
+
+- `pyproject.toml`
+- `ruff.toml`
+- `pytest.ini`
+- `tests/`
+- `docs/`
+
+## Modules
+
+| Module | Class | Description | Docs |
+|---|---|---|---|
+| `core` | N/A | Shared models, ports, exceptions, and prompt helpers | [docs](packages/core/docs/module-spec.md) |
+| `extract_text_from_image` | `ImageTextExtractor` | Extract Dutch text from images via Vision API | [docs](packages/extract_text_from_image/docs/module-spec.md) |
+| `extract_words_from_text` | `WordExtractor` | Extract and normalize words from markdown text | [docs](packages/extract_words_from_text/docs/module-spec.md) |
+| `translate_text` | `TextTranslator` | Translate text (NL -> RU) with markdown preservation | [docs](packages/translate_text/docs/module-spec.md) |
+| `translate_word` | `WordTranslator` | Batch-translate words (NL -> RU) | [docs](packages/translate_word/docs/module-spec.md) |
+| `database` | `DatabaseService` | Remote source of truth and default progress/sync provider | [docs](packages/database/docs/module-spec.md) |
+| `database_cache` | `DatabaseCacheService` | Local-first SQLite cache with injectable remote progress sync | [docs](packages/database_cache/docs/module-spec.md) |
+| `sampling` | `WordSampler` | Weighted word sampling over any compatible scored-pair provider | [docs](packages/sampling/docs/module-spec.md) |
+
+## Development
+
+Work inside one package when you only touch one module:
+
+```bash
+cd packages/translate_word
+uv sync --all-groups
+uv run pytest tests/unit
+```
+
+Run the repo-wide quality gate from the root:
+
+```bash
+make check
+```
+
+Useful package-local examples:
+
+```bash
+cd packages/core
+uv run pytest tests/unit/core
+
+cd packages/database
+doppler run -- uv run pytest tests/integration/database
+```
+
+## Dependency Rule
+
+Modules are independent packages. Cross-module dependencies must be explicit in the consuming package's `pyproject.toml`.
+
+Shared cross-module storage contracts live in `nl_processing.core.ports`. `database` and `database_cache` are concrete implementations and adapters, not the owners of those shared interfaces.
+
+One intentional design change in this layout: `database` no longer imports `translate_word` directly. If you want automatic translation on `add_words()`, compose it explicitly:
+
+```python
+from nl_processing.core.models import Language
+from nl_processing.database.service import DatabaseService
+from nl_processing.translate_word.service import WordTranslator
+
+db = DatabaseService(
+    user_id="alex",
+    translator=WordTranslator(
+        source_language=Language.NL,
+        target_language=Language.RU,
+    ),
+)
+```
+
+## Docs
+
+- Repository module spec: [docs/module-spec.md](docs/module-spec.md)
+- Environment variables: [docs/ENV_VARS.md](docs/ENV_VARS.md)
+- Release workflow: [docs/REALEASE_WORKFLOW.md](docs/REALEASE_WORKFLOW.md)

nl_processing-1.0.2/README.md

@@ -0,0 +1,105 @@
+# nl_processing
+
+[![PyPI](https://img.shields.io/pypi/v/nl_processing)](https://pypi.org/project/nl_processing/)
+
+Dutch language processing toolkit organized as a multi-package Python repository.
+
+## Install
+
+```bash
+pip install nl_processing
+```
+
+The published `nl_processing` package is the aggregate build from the repo root. Day-to-day development happens inside the package folders under `packages/`.
+
+## Repository Layout
+
+```text
+packages/
+  core/
+  extract_text_from_image/
+  extract_words_from_text/
+  translate_text/
+  translate_word/
+  database/
+  database_cache/
+  sampling/
+docs/
+pyproject.toml        # aggregate build for the published nl_processing package
+Makefile              # repo-wide lint/test entrypoint
+```
+
+Each package has its own:
+
+- `pyproject.toml`
+- `ruff.toml`
+- `pytest.ini`
+- `tests/`
+- `docs/`
+
+## Modules
+
+| Module | Class | Description | Docs |
+|---|---|---|---|
+| `core` | N/A | Shared models, ports, exceptions, and prompt helpers | [docs](packages/core/docs/module-spec.md) |
+| `extract_text_from_image` | `ImageTextExtractor` | Extract Dutch text from images via Vision API | [docs](packages/extract_text_from_image/docs/module-spec.md) |
+| `extract_words_from_text` | `WordExtractor` | Extract and normalize words from markdown text | [docs](packages/extract_words_from_text/docs/module-spec.md) |
+| `translate_text` | `TextTranslator` | Translate text (NL -> RU) with markdown preservation | [docs](packages/translate_text/docs/module-spec.md) |
+| `translate_word` | `WordTranslator` | Batch-translate words (NL -> RU) | [docs](packages/translate_word/docs/module-spec.md) |
+| `database` | `DatabaseService` | Remote source of truth and default progress/sync provider | [docs](packages/database/docs/module-spec.md) |
+| `database_cache` | `DatabaseCacheService` | Local-first SQLite cache with injectable remote progress sync | [docs](packages/database_cache/docs/module-spec.md) |
+| `sampling` | `WordSampler` | Weighted word sampling over any compatible scored-pair provider | [docs](packages/sampling/docs/module-spec.md) |
+
+## Development
+
+Work inside one package when you only touch one module:
+
+```bash
+cd packages/translate_word
+uv sync --all-groups
+uv run pytest tests/unit
+```
+
+Run the repo-wide quality gate from the root:
+
+```bash
+make check
+```
+
+Useful package-local examples:
+
+```bash
+cd packages/core
+uv run pytest tests/unit/core
+
+cd packages/database
+doppler run -- uv run pytest tests/integration/database
+```
+
+## Dependency Rule
+
+Modules are independent packages. Cross-module dependencies must be explicit in the consuming package's `pyproject.toml`.
+
+Shared cross-module storage contracts live in `nl_processing.core.ports`. `database` and `database_cache` are concrete implementations and adapters, not the owners of those shared interfaces.
+
+One intentional design change in this layout: `database` no longer imports `translate_word` directly. If you want automatic translation on `add_words()`, compose it explicitly:
+
+```python
+from nl_processing.core.models import Language
+from nl_processing.database.service import DatabaseService
+from nl_processing.translate_word.service import WordTranslator
+
+db = DatabaseService(
+    user_id="alex",
+    translator=WordTranslator(
+        source_language=Language.NL,
+        target_language=Language.RU,
+    ),
+)
+```
+
+## Docs
+
+- Repository module spec: [docs/module-spec.md](docs/module-spec.md)
+- Environment variables: [docs/ENV_VARS.md](docs/ENV_VARS.md)
+- Release workflow: [docs/REALEASE_WORKFLOW.md](docs/REALEASE_WORKFLOW.md)

nl_processing-1.0.2/nl_processing.egg-info/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: nl_processing
+Version: 1.0.2
+Summary: Aggregate build for the nl_processing multi-package repository
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: langchain-core<1,>=0.3
+Requires-Dist: langchain-openai<1,>=0.3
+Requires-Dist: numpy<3,>=2.0
+Requires-Dist: opencv-python<5,>=4.10
+Requires-Dist: asyncpg<1,>=0.30
+Requires-Dist: aiosqlite<1,>=0.20
+
+# nl_processing
+
+[![PyPI](https://img.shields.io/pypi/v/nl_processing)](https://pypi.org/project/nl_processing/)
+
+Dutch language processing toolkit organized as a multi-package Python repository.
+
+## Install
+
+```bash
+pip install nl_processing
+```
+
+The published `nl_processing` package is the aggregate build from the repo root. Day-to-day development happens inside the package folders under `packages/`.
+
+## Repository Layout
+
+```text
+packages/
+  core/
+  extract_text_from_image/
+  extract_words_from_text/
+  translate_text/
+  translate_word/
+  database/
+  database_cache/
+  sampling/
+docs/
+pyproject.toml        # aggregate build for the published nl_processing package
+Makefile              # repo-wide lint/test entrypoint
+```
+
+Each package has its own:
+
+- `pyproject.toml`
+- `ruff.toml`
+- `pytest.ini`
+- `tests/`
+- `docs/`
+
+## Modules
+
+| Module | Class | Description | Docs |
+|---|---|---|---|
+| `core` | N/A | Shared models, ports, exceptions, and prompt helpers | [docs](packages/core/docs/module-spec.md) |
+| `extract_text_from_image` | `ImageTextExtractor` | Extract Dutch text from images via Vision API | [docs](packages/extract_text_from_image/docs/module-spec.md) |
+| `extract_words_from_text` | `WordExtractor` | Extract and normalize words from markdown text | [docs](packages/extract_words_from_text/docs/module-spec.md) |
+| `translate_text` | `TextTranslator` | Translate text (NL -> RU) with markdown preservation | [docs](packages/translate_text/docs/module-spec.md) |
+| `translate_word` | `WordTranslator` | Batch-translate words (NL -> RU) | [docs](packages/translate_word/docs/module-spec.md) |
+| `database` | `DatabaseService` | Remote source of truth and default progress/sync provider | [docs](packages/database/docs/module-spec.md) |
+| `database_cache` | `DatabaseCacheService` | Local-first SQLite cache with injectable remote progress sync | [docs](packages/database_cache/docs/module-spec.md) |
+| `sampling` | `WordSampler` | Weighted word sampling over any compatible scored-pair provider | [docs](packages/sampling/docs/module-spec.md) |
+
+## Development
+
+Work inside one package when you only touch one module:
+
+```bash
+cd packages/translate_word
+uv sync --all-groups
+uv run pytest tests/unit
+```
+
+Run the repo-wide quality gate from the root:
+
+```bash
+make check
+```
+
+Useful package-local examples:
+
+```bash
+cd packages/core
+uv run pytest tests/unit/core
+
+cd packages/database
+doppler run -- uv run pytest tests/integration/database
+```
+
+## Dependency Rule
+
+Modules are independent packages. Cross-module dependencies must be explicit in the consuming package's `pyproject.toml`.
+
+Shared cross-module storage contracts live in `nl_processing.core.ports`. `database` and `database_cache` are concrete implementations and adapters, not the owners of those shared interfaces.
+
+One intentional design change in this layout: `database` no longer imports `translate_word` directly. If you want automatic translation on `add_words()`, compose it explicitly:
+
+```python
+from nl_processing.core.models import Language
+from nl_processing.database.service import DatabaseService
+from nl_processing.translate_word.service import WordTranslator
+
+db = DatabaseService(
+    user_id="alex",
+    translator=WordTranslator(
+        source_language=Language.NL,
+        target_language=Language.RU,
+    ),
+)
+```
+
+## Docs
+
+- Repository module spec: [docs/module-spec.md](docs/module-spec.md)
+- Environment variables: [docs/ENV_VARS.md](docs/ENV_VARS.md)
+- Release workflow: [docs/REALEASE_WORKFLOW.md](docs/REALEASE_WORKFLOW.md)

nl_processing-1.0.2/nl_processing.egg-info/SOURCES.txt

@@ -0,0 +1,52 @@
+README.md
+pyproject.toml
+nl_processing.egg-info/PKG-INFO
+nl_processing.egg-info/SOURCES.txt
+nl_processing.egg-info/dependency_links.txt
+nl_processing.egg-info/requires.txt
+nl_processing.egg-info/top_level.txt
+packages/core/src/nl_processing/core/__init__.py
+packages/core/src/nl_processing/core/exceptions.py
+packages/core/src/nl_processing/core/models.py
+packages/core/src/nl_processing/core/ports.py
+packages/core/src/nl_processing/core/prompts.py
+packages/database/src/nl_processing/database/__init__.py
+packages/database/src/nl_processing/database/exceptions.py
+packages/database/src/nl_processing/database/exercise_progress.py
+packages/database/src/nl_processing/database/logging.py
+packages/database/src/nl_processing/database/models.py
+packages/database/src/nl_processing/database/service.py
+packages/database/src/nl_processing/database/testing.py
+packages/database/src/nl_processing/database/backend/__init__.py
+packages/database/src/nl_processing/database/backend/_neon_exercise.py
+packages/database/src/nl_processing/database/backend/_queries.py
+packages/database/src/nl_processing/database/backend/abstract.py
+packages/database/src/nl_processing/database/backend/neon.py
+packages/database_cache/src/nl_processing/database_cache/__init__.py
+packages/database_cache/src/nl_processing/database_cache/_local_store_queries.py
+packages/database_cache/src/nl_processing/database_cache/exceptions.py
+packages/database_cache/src/nl_processing/database_cache/local_store.py
+packages/database_cache/src/nl_processing/database_cache/logging.py
+packages/database_cache/src/nl_processing/database_cache/models.py
+packages/database_cache/src/nl_processing/database_cache/service.py
+packages/database_cache/src/nl_processing/database_cache/sync.py
+packages/extract_text_from_image/src/nl_processing/extract_text_from_image/__init__.py
+packages/extract_text_from_image/src/nl_processing/extract_text_from_image/benchmark.py
+packages/extract_text_from_image/src/nl_processing/extract_text_from_image/image_encoding.py
+packages/extract_text_from_image/src/nl_processing/extract_text_from_image/service.py
+packages/extract_text_from_image/src/nl_processing/extract_text_from_image/prompts/generate_nl_prompt.py
+packages/extract_text_from_image/src/nl_processing/extract_text_from_image/prompts/nl.json
+packages/extract_words_from_text/src/nl_processing/extract_words_from_text/__init__.py
+packages/extract_words_from_text/src/nl_processing/extract_words_from_text/service.py
+packages/extract_words_from_text/src/nl_processing/extract_words_from_text/prompts/generate_nl_prompt.py
+packages/extract_words_from_text/src/nl_processing/extract_words_from_text/prompts/nl.json
+packages/sampling/src/nl_processing/sampling/__init__.py
+packages/sampling/src/nl_processing/sampling/service.py
+packages/translate_text/src/nl_processing/translate_text/__init__.py
+packages/translate_text/src/nl_processing/translate_text/service.py
+packages/translate_text/src/nl_processing/translate_text/prompts/generate_nl_ru_prompt.py
+packages/translate_text/src/nl_processing/translate_text/prompts/nl_ru.json
+packages/translate_word/src/nl_processing/translate_word/__init__.py
+packages/translate_word/src/nl_processing/translate_word/service.py
+packages/translate_word/src/nl_processing/translate_word/prompts/generate_nl_ru_prompt.py
+packages/translate_word/src/nl_processing/translate_word/prompts/nl_ru.json

{nl_processing-0.5.0 → nl_processing-1.0.2}/nl_processing.egg-info/requires.txt

@@ -1,6 +1,7 @@
 pydantic<3,>=2.0
-langchain<1,>=0.3
+langchain-core<1,>=0.3
 langchain-openai<1,>=0.3
+numpy<3,>=2.0
 opencv-python<5,>=4.10
 asyncpg<1,>=0.30
 aiosqlite<1,>=0.20

{nl_processing-0.5.0 → nl_processing-1.0.2/packages/core/src}/nl_processing/core/models.py

@@ -45,3 +45,22 @@ class Word(BaseModel):
     normalized_form: str
     word_type: PartOfSpeech
     language: Language
+
+
+class WordPair(BaseModel):
+    source: Word
+    target: Word
+
+
+class ScoredWordPair(BaseModel):
+    """Translated pair with per-exercise scores and a stable source-word ID."""
+
+    pair: WordPair
+    scores: dict[str, int]
+    source_word_id: int
+
+
+class WordPairSnapshot(ScoredWordPair):
+    """Remote sync snapshot with stable source and target IDs for cache rebuilds."""
+
+    target_word_id: int

nl_processing-1.0.2/packages/core/src/nl_processing/core/ports.py

@@ -0,0 +1,25 @@
+from typing import Protocol, runtime_checkable
+
+from nl_processing.core.models import ScoredWordPair, WordPairSnapshot
+
+
+@runtime_checkable
+class ScoredPairProvider(Protocol):
+    """Provider of score-aware word pairs for sampling or practice flows."""
+
+    async def get_word_pairs_with_scores(self) -> list[ScoredWordPair]: ...
+
+
+@runtime_checkable
+class RemoteProgressSyncPort(Protocol):
+    """Remote sync contract consumed by the local cache layer."""
+
+    async def export_remote_snapshot(self) -> list[WordPairSnapshot]: ...
+
+    async def apply_score_delta(
+        self,
+        event_id: str,
+        source_word_id: int,
+        exercise_type: str,
+        delta: int,
+    ) -> None: ...

{nl_processing-0.5.0 → nl_processing-1.0.2/packages/database/src}/nl_processing/database/exercise_progress.py

@@ -1,15 +1,16 @@
 """ExerciseProgressStore — per-user, per-exercise score tracking.
 
-Internal API consumed by the sampling module to determine which
-words to practice based on exercise-specific scores.
+Default implementation of the shared scored-pair and remote-progress
+sync contracts used by sampling and database_cache.
 """
 
 import os
 
-from nl_processing.core.models import Language, PartOfSpeech, Word
+from nl_processing.core.models import Language, PartOfSpeech, ScoredWordPair, Word, WordPair, WordPairSnapshot
+
+from nl_processing.database.backend.abstract import AbstractBackend
 from nl_processing.database.backend.neon import NeonBackend
 from nl_processing.database.exceptions import ConfigurationError
-from nl_processing.database.models import ScoredWordPair, WordPair
 
 _DATABASE_URL_MISSING = (
     "DATABASE_URL environment variable is required. "
@@ -27,7 +28,7 @@ def _read_database_url() -> str:
 
 
 class ExerciseProgressStore:
-    """Per-user, per-exercise score tracking and score-aware word pair retrieval."""
+    """Per-user progress store for score-aware reads and remote cache sync."""
 
     def __init__(
         self,
@@ -36,12 +37,16 @@ class ExerciseProgressStore:
         source_language: Language,
         target_language: Language,
         exercise_types: list[str],
+        backend: AbstractBackend | None = None,
     ) -> None:
         if not exercise_types:
             msg = "exercise_types must be a non-empty list"
             raise ValueError(msg)
-        database_url = _read_database_url()
-        self._backend = NeonBackend(database_url)
+        if backend is None:
+            database_url = _read_database_url()
+            self._backend: AbstractBackend = NeonBackend(database_url)
+        else:
+            self._backend = backend
         self._user_id = user_id
         self._source_language = source_language
         self._target_language = target_language
@@ -78,23 +83,9 @@ class ExerciseProgressStore:
 
         Missing scores default to 0 (FR33).
         """
-        rows = await self._backend.get_user_words(
-            self._user_id,
-            self._source_language.value,
-        )
+        rows, scores_by_word = await self._get_rows_with_scores()
         if not rows:
             return []
-        source_word_ids = [int(row["source_id"]) for row in rows]
-        scores_by_word: dict[int, dict[str, int]] = {}
-        for et, table in self._score_tables.items():
-            score_rows = await self._backend.get_user_exercise_scores(
-                table,
-                self._user_id,
-                source_word_ids,
-            )
-            for score_row in score_rows:
-                wid = int(score_row["source_word_id"])
-                scores_by_word.setdefault(wid, {})[et] = int(score_row["score"])
         result: list[ScoredWordPair] = []
         for row in rows:
             pair = self._row_to_word_pair(row)
@@ -106,9 +97,27 @@ class ExerciseProgressStore:
             )
         return result
 
-    async def export_remote_snapshot(self) -> list[ScoredWordPair]:
-        """Thin wrapper around get_word_pairs_with_scores for cache consumers."""
-        return await self.get_word_pairs_with_scores()
+    async def export_remote_snapshot(self) -> list[WordPairSnapshot]:
+        """Return score-aware pairs with stable remote IDs for cache consumers."""
+        rows, scores_by_word = await self._get_rows_with_scores()
+        if not rows:
+            return []
+        snapshots: list[WordPairSnapshot] = []
+        for row in rows:
+            pair = self._row_to_word_pair(row)
+            source_word_id = int(row["source_id"])
+            target_word_id = int(row["target_id"])
+            word_scores = scores_by_word.get(source_word_id, {})
+            scores = {et: word_scores.get(et, 0) for et in self._exercise_types}
+            snapshots.append(
+                WordPairSnapshot(
+                    pair=pair,
+                    scores=scores,
+                    source_word_id=source_word_id,
+                    target_word_id=target_word_id,
+                ),
+            )
+        return snapshots
 
     async def apply_score_delta(
         self,
@@ -142,6 +151,29 @@ class ExerciseProgressStore:
             msg = f"Unknown exercise_type '{exercise_type}'; expected one of {sorted(self._score_tables)}"
             raise ValueError(msg)
 
+    async def _get_rows_with_scores(
+        self,
+    ) -> tuple[list[dict[str, str | int]], dict[int, dict[str, int]]]:
+        """Fetch translated rows and per-exercise scores for the current user."""
+        rows = await self._backend.get_user_words(
+            self._user_id,
+            self._source_language.value,
+        )
+        if not rows:
+            return [], {}
+        source_word_ids = [int(row["source_id"]) for row in rows]
+        scores_by_word: dict[int, dict[str, int]] = {}
+        for exercise_type, table in self._score_tables.items():
+            score_rows = await self._backend.get_user_exercise_scores(
+                table,
+                self._user_id,
+                source_word_ids,
+            )
+            for score_row in score_rows:
+                wid = int(score_row["source_word_id"])
+                scores_by_word.setdefault(wid, {})[exercise_type] = int(score_row["score"])
+        return rows, scores_by_word
+
     def _word_from_row(
         self,
         row: dict[str, str | int],

nl_processing-1.0.2/packages/database/src/nl_processing/database/models.py

@@ -0,0 +1,7 @@
+from nl_processing.core.models import Word
+from pydantic import BaseModel
+
+
+class AddWordsResult(BaseModel):
+    new_words: list[Word]
+    existing_words: list[Word]

{nl_processing-0.5.0 → nl_processing-1.0.2/packages/database/src}/nl_processing/database/service.py

@@ -6,13 +6,15 @@ and retrieving Word objects backed by Neon PostgreSQL.
 
 import asyncio
 import os
+from typing import Protocol
 
-from nl_processing.core.models import Language, PartOfSpeech, Word
+from nl_processing.core.models import Language, PartOfSpeech, Word, WordPair
+
+from nl_processing.database.backend.abstract import AbstractBackend
 from nl_processing.database.backend.neon import NeonBackend
 from nl_processing.database.exceptions import ConfigurationError
 from nl_processing.database.logging import get_logger
-from nl_processing.database.models import AddWordsResult, WordPair
-from nl_processing.translate_word.service import WordTranslator
+from nl_processing.database.models import AddWordsResult
 
 _logger = get_logger("service")
 
@@ -31,6 +33,10 @@ def _read_database_url() -> str:
         raise ConfigurationError(_DATABASE_URL_MISSING) from exc
 
 
+class WordTranslatorProtocol(Protocol):
+    async def translate(self, words: list[Word]) -> list[Word]: ...
+
+
 class DatabaseService:
     """Async service for persisting and retrieving words with translations."""
 
@@ -40,13 +46,15 @@ class DatabaseService:
         user_id: str,
         source_language: Language = Language.NL,
         target_language: Language = Language.RU,
+        backend: AbstractBackend | None = None,
+        translator: WordTranslatorProtocol | None = None,
     ) -> None:
-        database_url = _read_database_url()
-        self._backend = NeonBackend(database_url)
-        self._translator = WordTranslator(
-            source_language=source_language,
-            target_language=target_language,
-        )
+        if backend is None:
+            database_url = _read_database_url()
+            self._backend: AbstractBackend = NeonBackend(database_url)
+        else:
+            self._backend = backend
+        self._translator = translator
         self._user_id = user_id
         self._source_language = source_language
         self._target_language = target_language
@@ -79,13 +87,15 @@ class DatabaseService:
                 new_words.append(word)
             await self._backend.add_user_word(self._user_id, word_id, word.language.value)
 
-        if new_words:
-            asyncio.create_task(self._translate_and_store(new_words))
+        new_source_words = [word for word in new_words if word.language == self._source_language]
+        if new_source_words and self._translator is not None:
+            asyncio.create_task(self._translate_and_store(new_source_words))
 
         return AddWordsResult(new_words=new_words, existing_words=existing_words)
 
     async def _translate_and_store(self, new_words: list[Word]) -> None:
         """Translate new words and store translations (fire-and-forget)."""
+        assert self._translator is not None
         try:
             translated = await self._translator.translate(new_words)
             for source_word, target_word in zip(new_words, translated):