Translator API

API-only Rails app for managing glossaries, terms, and translations.

Requirements

• Ruby 4.0.0
• Bundler
• SQLite3

Setup

bundle install
bundle exec rails db:setup

Run

bundle exec rails server

Production

Set the secret key base:

export SECRET_KEY_BASE=your_secret_key_base

Generate one with:

bundle exec rails secret

Tests

bundle exec rails test

API Endpoints

• POST /glossaries create a glossary
• GET /glossaries/:id fetch a glossary with terms
• GET /glossaries list glossaries with terms
• POST /glossaries/:id/terms create a term in a glossary
• POST /translations create a translation
• GET /translations/:id fetch a translation with highlighted terms

Validation Rules

• Glossaries are unique per source_language_code + target_language_code.
• Language codes must be valid ISO 639-1 values (see config/iso-639-1.csv).
• Terms require non-blank source_term and target_term.
• Translations require source_language_code, target_language_code, and source_text.
• source_text is limited to 5000 characters.
• When glossary_id is provided, translation language codes must match the glossary.

Error Responses

• 422: { "errors": ["..."] }
• 404: { "error": "Not Found" }

Examples

Create a glossary:

curl -X POST http://localhost:3000/glossaries \
  -H 'Content-Type: application/json' \
  -d '{"glossary":{"source_language_code":"en","target_language_code":"fr"}}'

Create a term:

curl -X POST http://localhost:3000/glossaries/1/terms \
  -H 'Content-Type: application/json' \
  -d '{"term":{"source_term":"recruitment","target_term":"recrutement"}}'

Create a translation:

curl -X POST http://localhost:3000/translations \
  -H 'Content-Type: application/json' \
  -d '{"translation":{"source_language_code":"en","target_language_code":"fr","source_text":"This is a recruitment task.","glossary_id":1}}'

Fetch a translation (with highlighted terms):

curl http://localhost:3000/translations/1

Example response:

{
  "id": 1,
  "source_language_code": "en",
  "target_language_code": "fr",
  "source_text": "This is a <HIGHLIGHT>recruitment</HIGHLIGHT> task.",
  "glossary_id": 1,
  "matching_terms": [
    {
      "id": 1,
      "source_term": "recruitment",
      "target_term": "recrutement"
    }
  ]
}

Docker

docker build -t translator_api .
docker run --rm -p 3000:3000 -v "$(pwd)/db:/app/db" translator_api

If you need to initialize the database inside the container:

docker run --rm -p 3000:3000 -v "$(pwd)/db:/app/db" translator_api bundle exec rails db:prepare