Download the PHP package habr/bblslug without Composer

Bblslug

Bblslug is a versatile translation tool that can be used as both a CLI utility and a PHP library.

It leverages LLM-based APIs to translate plain text, HTML and JSON while preserving structure, code blocks, and URLs via placeholder filters.

APIs supported:

• Anthropic (Claude):
  • anthropic:claude-haiku-3.5 - Claude Haiku 3.5 (latest)
  • anthropic:claude-opus-4 - Claude Opus 4 (20250514)
  • anthropic:claude-sonnet-4 - Claude Sonnet 4 (20250514)
• DeepL:
  • deepl:free - DeepL free tier
  • deepl:pro - DeepL pro tier
• Google (Gemini):
  • google:gemini-2.5-flash - Gemini 2.5 Flash
  • google:gemini-2.5-flash-lite - Gemini 2.5 Flash Lite
  • google:gemini-2.5-pro - Gemini 2.5 Pro
  • google:gemini-2.0-flash - Gemini 2.0 Flash
• OpenAI (GPT):
  • openai:gpt-5 - OpenAI GPT-5
  • openai:gpt-5-mini - OpenAI GPT-5 Mini
  • openai:gpt-5-nano - OpenAI GPT-5 Nano
  • openai:gpt-4o - OpenAI GPT-4o
  • openai:gpt-4o-mini - OpenAI GPT-4o Mini
  • openai:gpt-4 - OpenAI GPT-4
  • openai:gpt-4-turbo - OpenAI GPT-4 Turbo
• Yandex:
  • yandex:gpt-lite - YandexGPT Lite
  • yandex:gpt-pro - YandexGPT Pro
  • yandex:gpt-32k - YandexGPT Pro 32K
• X.ai:
  • xai:grok-4 - Grok 4
  • xai:grok-3 - Grok 3
  • xai:grok-3-mini - Grok 3 Mini

Features

• Supports HTML, JSON and plain text (--format=text|html|json)
• Placeholder-based protection with filters: html_pre, html_code, url, etc.
• Model selection via --model=vendor:name
• Fully configurable backend registry (via resources/models.yaml)
• Dry-run mode to preview placeholders without making API calls
• Variables (--variables) to send or override model-specific options
• Verbose mode (--verbose) to print request previews
• Can be invoked as a CLI tool or embedded in PHP code
• Validation of container syntax for HTML or JSON; disable with --no-validate

Installation

CLI Usage

Prepare

1. Always specify a model with --model=vendor:name option.

2. Export your API key(s) before running:

   NB! Some vendors require additional parameters, e.g. YANDEX_FOLDER_ID.

3. Input / output:

   • If --source is omitted, Bblslug reads from STDIN.
   • If --translated is omitted, Bblslug writes to STDOUT.

4. Optional proxy:

   To route requests through a proxy (e.g. HTTP or SOCKS5), use the --proxy option or set the BBLSLUG_PROXY environment variable:

   This works for all HTTP requests and supports authentication (http://user:pass@host:port).

Show available models

Show available prompt templates

Translate an HTML file and write to another file

Translate an JSON file and write to another file

Translate an HTML file and write to another file with filters

Add translation context (prompt), source and target language

Pass model-specific variables

Choose a different prompt template

Dry-run placeholders only

Verbose mode (prints request preview to stderr)

Pipe STDIN → file

Pipe STDIN → STDOUT

Disable validation

For HTML and JSON formats, Bblslug performs basic syntax validation before and after translation. To skip this step, add:

Statistics

• Usage metrics

  After each translation (when not in dry-run), Bblslug prints to stderr a summary of consumed usage metrics, for example:

PHP Library Usage

You can embed Bblslug in your PHP project.

Quickstart

1. Install:

2. Require & Import:

Translate

Text translation function example:

Result structure:

List available models

Returns an array like:

List available prompts

Returns an array like:

Error handling

Samples

You can find sample input files under the samples/ directory.

License

This project is licensed under the MIT License – see the LICENSE file for details.