Skip to content

feat: add --lang flag for translating non-English text queries - #308

Open
SergeyKarleev wants to merge 1 commit into
yurijmikhalevich:mainfrom
SergeyKarleev:feature/translate-queries
Open

feat: add --lang flag for translating non-English text queries#308
SergeyKarleev wants to merge 1 commit into
yurijmikhalevich:mainfrom
SergeyKarleev:feature/translate-queries

Conversation

@SergeyKarleev

@SergeyKarleev SergeyKarleev commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

How does this PR impact the user?

rclip's CLIP model only understands English, so non-English text queries used to search poorly with no way to fix it. This adds an optional translate extra and a --lang flag:

pip install "rclip[translate]"
rclip "un gato en el sofá" --lang es
  • --lang CODE (ISO 639-1, e.g. es) force-translates the query to English, downloading that language's small NMT package (via argostranslate) on first use.
  • Bare --lang (no code) uses the system locale's language.
  • Once a language's package is installed, later plain queries in that language auto-translate too, based on the system locale — no need to keep passing --lang.
  • Without --lang, nothing changes for existing users: no implicit language detection, no surprise network calls or downloads on a plain search.
  • Unknown codes get "did you mean" suggestions, e.g. no translation package found for language "esp"; did you mean: es, pt, eo?.

Description

  • rclip/translate.py (new) — language-package install/cache (ensure_language_installed, _has_installed_package) and the actual translate call (translate_to_english), plus the --lang value resolution (resolve_forced_lang).

  • rclip/model.pyModel takes an optional forced_lang; phrase queries are run through translate_to_english before hitting the (English-only) CLIP text encoder. File-path and URL queries are never translated.

  • rclip/main.py / rclip/utils/helpers.py — new --lang [CODE] CLI flag; the language package is installed eagerly at startup (clear failure up front, not mid-search).

  • pyproject.toml — new optional translate extra (argostranslate).

  • Manually verified translation quality across 9 languages/scripts (Latin, Cyrillic, CJK, Arabic) before opening this PR:

    Lang Query Translated
    es un gato negro en el sofá A black cat on his couch.
    ru Чёрная кошка на диване Black cat on the couch.
    de Ein schwarzer Hund im Park A black dog in the park.
    it Un gatto nero sul divano A black cat on the couch.
    fr un chat noir sur le canapé A black cat on the couch.
    ko 공원에 있는 검은 개 Black dog in the park.
    ja 公園にいる黒い犬 Black dog in the park.
    zh 公园里的黑狗 Black dogs in the park.
    ar كلب أسود في الحديقة Black dog in the park.

Limitations

  • Translation quality depends on argostranslate's small NMT models — works well for concrete queries, idioms/figurative language can lose nuance.
  • The translate extra is not auto-installed if missing (only the language model is); doing so safely isn't possible across all of rclip's install methods (brew/snap/AppImage bundles have no writable, pip-able environment). --lang fails fast with the install command instead.
  • argostranslate's heavy dependency (ctranslate2) ships wheels for macOS (arm64/x86_64), Linux (manylinux x86_64/aarch64), and Windows (win_amd64) — verified on PyPI, not separately smoke-tested on Linux/Windows in this PR.

Checklist

  • my PR is focused and contains one holistic change
  • I have added screenshots or screen recordings to show the changes

rclip's CLIP model only understands English, so non-English text
queries used to search poorly. Add an optional "translate" extra
(argostranslate) and a --lang [CODE] flag: pass a language code (or
omit it to use the system locale's language) to force-translate the
query to English, downloading that language's small NMT package on
first use.

Without --lang, a query only auto-translates if that language's
package is already installed from a previous --lang run -- there's no
implicit language detection and no surprise network calls or
downloads on a plain search.

--lang forces translation even for ASCII-only input, since many
languages (Spanish, German, Italian, ...) are frequently written
without any non-ASCII characters. An unknown language code gets
"did you mean" suggestions from the package index instead of a bare
failure.
Comment thread rclip/utils/helpers.py

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi! Thank you for proposing this! I was planning to add support for other languages in rclip, but I am not sure if this is the best direction we can take.

To understand this, I'll first need to benchmark this solution (both quality and speed) against:

  • sentence-transformers/clip-ViT-B-32-multilingual-v1
  • siglip-base-patch16-256-i18n

These are both CLIP models, which handle multiple languages natively and are in the same "weight class" as the model rclip uses currently, making them good candidates to solve this problem.

If you can benchmark them, I'd appreciate it and might merge something sooner. Otherwise, I'll decide on the way forward once I've benchmarked them myself.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants