README.md
Rama main · réplica de lectura del repositorio original.
[](https://scorecard.dev/viewer/?uri=github.com/HereTrix/strings_repository)
[](https://www.bestpractices.dev/projects/12778)
[](https://codecov.io/github/HereTrix/strings_repository)
# StringsRepository
**StringsRepository** is a self-hosted translation management service for product teams that want full control without the complexity of a general-purpose platform. It's designed around an API/CLI-first workflow: translators work in the UI, developers push and pull strings from CI. Deploy it in a single Docker container, own the data, and extend the code directly.
## Features
* **Multiple project support** - manage translations for multiple projects independently
* **User roles & access control** - per-project roles with an invitation system for team collaboration
* **Multi-language support** - configure and manage any number of target languages per project
* **Translation management** - create, update, and track translation status for each string key
* **Plural forms** - full CLDR plural form support (zero, one, two, few, many, other)
* **Custom tags** - organize and group translations using custom tags
* **Scopes** - group string keys into named scopes with optional context images; translators browse translations by scope in a visual gallery
* **Import & export** - import/export translations in multiple supported formats
* **Translation bundles** - versioned snapshots of translations for safe production releases and rollbacks
* **Live bundle serving** - expose a project's live bundle over a tokenized public API so mobile apps and backend services can fetch translations directly, with tag/scope filtering and on-demand caching
* **Machine translation** - DeepL, Google Translate, and Generic AI (any OpenAI-compatible REST API) integration
* **AI translation verification** - async quality audits powered by any OpenAI-compatible or Anthropic-compatible provider; source quality and translation accuracy modes with per-check selection, scope/tag filtering, suggestion review, and one-click apply
* **Two-factor authentication (2FA)** - TOTP-based 2FA per user account; project owners can require 2FA for all project members
* **Glossary** - manage domain-specific terms with definitions and per-language preferred translations; AI-powered term extraction from existing strings; import/export support
* **Translation memory** - automatically surface previously-translated strings similar to the current source text to improve consistency
* **Passkeys (WebAuthn)** - passwordless authentication via FIDO2/passkeys as an alternative to passwords
* **MCP support** - AI-agent integration via Model Context Protocol for IDE-based key management and localization workflows
* **Webhooks** - real-time event notifications to external services
* **Full change history** - track all translation changes with an exportable history log
* **Figma plugin** - integrate design workflows
https://github.com/HereTrix/strings_repository-figma-plugin
* **CLI application** - integrate localization into CI/CD pipelines
https://github.com/HereTrix/strings_repository_cli
## Tech Stack
| Layer | Technology |
| -------------- | --------------------------------------------------------------------------- |
| Backend | Python / Django REST Framework |
| Authentication | Knox token-based authentication |
| Frontend | React (TypeScript) with React Router |
| Database | SQLite (default) or any Django-supported database (PostgreSQL, MySQL, etc.) |
| Deployment | Docker |
## Supported File Formats
| Type value | Format | Extension | Import | Export |
| -------------- | ----------------------------- | ------------- | ------ | ------ |
| `strings` | Apple (.strings) | `.strings` | ✓ | ✓ |
| `xcstrings` | Apple Xcode (.xcstrings) | `.xcstrings` | ✓ | ✓ |
| `xml` | Android | `.xml` | ✓ | ✓ |
| `excel` | Excel (separate sheets) | `.xlsx` | | ✓ |
| `xlsx` | Excel (single sheet) | `.xlsx` | | ✓ |
| `json` | JSON — Key/Value (i18next) | `.json` | ✓ | ✓ |
| `json_dict` | JSON — Key/Dictionary | `.json` | | ✓ |
| `resx` | ASP.NET | `.resx` | ✓ | ✓ |
| `properties` | Java | `.properties` | ✓ | ✓ |
| `po` | Portable Object | `.po` | ✓ | ✓ |
| `mo` | Binary MO | `.mo` | ✓ | ✓ |
| `csv` | CSV | `.csv` | ✓ | ✓ |
| `arb` | Flutter ARB | `.arb` | ✓ | ✓ |
## Translation Bundles
Bundles are versioned snapshots of all project translations. Pin a release state, roll back, compare against live, or export from any snapshot. The export endpoint accepts a `bundle_version` field to select live data, the active bundle, or a specific named version.
See [docs/bundles.md](docs/bundles.md) for the full workflow and API reference.
## Live Bundle Serving
Enable per-project public serving of the live bundle so client applications can fetch translations directly over HTTP using a dedicated access token, with optional tag/scope filtering and on-demand disk caching.
See [docs/live-bundle.md](docs/live-bundle.md) for the full API reference.
## Figma Plugin API
Three dedicated endpoints support the Figma plugin workflow: fetching available tags and scopes, pulling translations with optional tag/scope filters, and uploading per-frame context screenshots.
See [docs/plugin.md](docs/plugin.md) for the full API reference.
## Webhooks
Webhooks deliver real-time event notifications to external services. Each endpoint is configured with a URL, event subscriptions, an optional auth token, an optional payload template, and an auto-generated HMAC-SHA256 signing secret.
See [docs/webhooks.md](docs/webhooks.md) for the full event list and configuration reference.
## MCP Integration
StringsRepository exposes a [Model Context Protocol](https://modelcontextprotocol.io) endpoint at `POST /api/mcp`, enabling AI agents and IDE assistants (Claude Code, Cursor, VS Code) to manage localization keys without leaving the editor.
See [docs/mcp.md](docs/mcp.md) for the full tool reference and IDE setup instructions.
## Machine Translation
DeepL, Google Translate, and any OpenAI-compatible AI provider can be configured per project to auto-translate string keys. An API key for the chosen provider is stored encrypted at rest and can be verified before use.
The **Generic AI** option lets you connect any REST-based LLM without additional dependencies. Provide an endpoint URL, a JSON payload template (using `{{text}}`, `{{target_lang}}`, and optionally `{{source_lang}}` placeholders), and a dot-notation response path to extract the translated text (e.g. `choices.0.message.content`). Built-in presets are available for OpenAI / DeepSeek, Claude, and Ollama (local).
## Two-Factor Authentication (2FA)
Users can enable TOTP-based 2FA on their account via **Profile → Security**. Any standard authenticator app (Google Authenticator, Authy, etc.) can be used to scan the QR code. Backup codes are generated at setup time.
Project owners can enforce 2FA across their entire team. When enabled, any member without active 2FA will receive a `403` on all project API calls until they complete setup. The requirement can be toggled in **Project → Info → Security Settings**.
## AI Translation Verification
AI verification runs async quality audits on your translations using any OpenAI-compatible or Anthropic-compatible provider. Two modes are available: source quality (spelling, grammar, tone) and translation accuracy (semantic correctness against a target language). Results include severity badges, word-level diffs, and one-click apply.
See [docs/verification.md](docs/verification.md) for modes, workflow, and report management details.
## Configuration
## Quick Start
The fastest way to run StringsRepository is with Docker using SQLite:
```bash
docker run -d -p 8080:8080 \
-v sr_data:/app/media \
-e APP_SECRET_KEY=change-me \
-e DB_ENGINE=sqlite3 \
-e DB_NAME=/app/db.sqlite3 \
-e DJANGO_SUPERUSER_USERNAME=admin \
-e DJANGO_SUPERUSER_EMAIL=admin@example.com \
-e DJANGO_SUPERUSER_PASSWORD=adminpassword \
-e WEBAUTHN_RP_ID=localhost \
ghcr.io/heretrix/strings_repository:main
```
Then open **http://localhost:8080** and sign in with the credentials above.
Once logged in:
1. **Create a project** — click **New Project** and give it a name.
2. **Add languages** — go to **Project → Languages** and add your target languages.
3. **Add string keys** — use **Project → Tokens** to create your first localization key.
4. **Export translations** — go to **Project → Export**, choose a file format, and download.
For production deployments (PostgreSQL, TLS, persistent storage) see [Installation](#installation) below.
## Configuration
Before installation, configure the required environment variables.
| Variable | Description |
| --------------------------- | -------------------------------------------------------- |
| `APP_SECRET_KEY` | Django secret key (any random string) |
| `ALLOWED_HOSTS` | Allowed hosts separated by commas, or empty to allow all |
| `DB_ENGINE` | Database engine — see table below |
| `DB_NAME` | Database name (or file path for SQLite) |
| `DB_HOST` | Database host (not required for SQLite) |
| `DB_PORT` | Database port (not required for SQLite) |
| `DB_USER` | Database user (not required for SQLite) |
| `DB_PASSWORD` | Database password (not required for SQLite) |
| `DJANGO_SUPERUSER_USERNAME` | Admin username |
| `DJANGO_SUPERUSER_EMAIL` | Admin email |
| `DJANGO_SUPERUSER_PASSWORD` | Admin password |
| `WEBAUTHN_RP_ID` | WebAuthn relying party ID (your domain) |
| `WEBAUTHN_RP_NAME` | WebAuthn display name (StringsRepository by default) |
| `WEBAUTHN_ORIGIN` | WebAuthn origin URL (e.g. `https://your.domain`) |
| `CORS_ORIGINS` | Comma-separated allowed CORS origins (optional) |
| `DEBUG` | Set to `True` to enable Django debug mode (default: False) |
| `FIELD_ENCRYPTION_KEY_HASH` | Hash algorithm for field-encryption key derivation: `sha256` (default), `sha384`, `sha512`. Changing this requires re-encrypting all stored fields. |
### Supported databases
| `DB_ENGINE` value | Database | Driver (bundled) |
| ----------------- | -------------------- | ------------------------ |
| `sqlite3` | SQLite | built-in |
| `postgresql` | PostgreSQL 12+ | `psycopg` (v3) |
| `mysql` | MySQL 8+ / MariaDB | `mysqlclient` |
## Installation
### Docker
```bash
docker pull ghcr.io/heretrix/strings_repository:main
```
#### Building a leaner image
By default the image bundles drivers for all supported databases. If you build the image yourself you can include only the driver you need via the `DB` build argument:
| `DB` value | Installed drivers | Use when |
| -------------- | ------------------------- | ---------------------- |
| `all` (default)| PostgreSQL + MySQL | pre-built / unknown |
| `sqlite` | none (built-in) | SQLite only |
| `postgresql` | psycopg (v3) | PostgreSQL |
| `mysql` | mysqlclient | MySQL / MariaDB |
```bash
# PostgreSQL-only image (~30 MB smaller than the default)
docker build --build-arg DB=postgresql -t strings-repository .
# MySQL/MariaDB-only image
docker build --build-arg DB=mysql -t strings-repository .
# SQLite only (smallest image, no native libraries)
docker build --build-arg DB=sqlite -t strings-repository .
```
The pre-built image published to `ghcr.io` always uses `DB=all` so no rebuild is needed when pulling it.
#### docker run
Run with environment variables passed directly:
```bash
docker run -d -p 8080:8080 \
-v media_data:/app/media \
-e APP_SECRET_KEY=your-secret-key \
-e ALLOWED_HOSTS=yourdomain.com \
-e DB_ENGINE=postgresql \
-e DB_NAME=stringsdb \
-e DB_HOST=db \
-e DB_PORT=5432 \
-e DB_USER=dbuser \
-e DB_PASSWORD=dbpassword \
-e DJANGO_SUPERUSER_USERNAME=admin \
-e DJANGO_SUPERUSER_EMAIL=admin@example.com \
-e DJANGO_SUPERUSER_PASSWORD=adminpassword \
-e WEBAUTHN_RP_ID=your.domain \
-e WEBAUTHN_RP_NAME=StringsRepository \
ghcr.io/heretrix/strings_repository:main
```
The `-v media_data:/app/media` mount keeps uploaded scope images and other user files across container updates. Without it uploads are lost when the container is replaced.
Or use an env file:
```bash
docker run -d -p 8080:8080 -v media_data:/app/media --env-file .env ghcr.io/heretrix/strings_repository:main
```
### Manual installation
Requires **Node.js (npm)** and **Python (pip)**.
```bash
cd webui
npm install
npm run build
cd ..
pip install -r requirements.txt
```
Then install the driver for your database (SQLite needs none — it is built into Python):
```bash
# PostgreSQL
pip install -r requirements-postgresql.txt
# MySQL / MariaDB
pip install -r requirements-mysql.txt
```
```bash
python manage.py makemigrations api
python manage.py migrate
python manage.py createsuperuser
```
## Upgrading
Only the latest release receives security fixes and bug fixes. Upgrade as soon as a new version is available.
Check [CHANGELOG.md](CHANGELOG.md) before upgrading — breaking changes and any required manual steps are listed there under the relevant version.
### Docker
Pull the new image and restart the container. Database migrations and static file collection run automatically on startup via the entrypoint script:
```bash
docker pull ghcr.io/heretrix/strings_repository:latest
docker stop <container-name>
docker rm <container-name>
docker run ... # same options as before
```
No manual migration step is required.
### Manual installation
```bash
git pull
pip install -r requirements.txt # pick up new or updated dependencies
python manage.py migrate # apply database migrations
cd webui && npm ci && npm run build # rebuild the frontend
```
Restart the application process after the above steps complete.
## Usage
Detailed usage instructions are available in the project wiki:
https://github.com/HereTrix/strings_repository/wiki
## Related Tools
* CLI client
https://github.com/HereTrix/strings_repository_cli
* Figma plugin
https://github.com/HereTrix/strings_repository-figma-plugin
## Contributing
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
StringsRepository is released under the **MIT License**.
See the `LICENSE` file for details.