227 lines
6.1 KiB
Markdown
227 lines
6.1 KiB
Markdown
# Specification: Translation Dictionary for Living Christianity
|
|
|
|
## Overview
|
|
|
|
"Sanasto Wiki" is a web-based glossary for simultaneous translators in the living Christianity. The application provides publicly accessible translations while restricting editing and commenting to invited contributors.
|
|
|
|
---
|
|
|
|
## Core Concepts
|
|
|
|
### Supported Languages
|
|
|
|
Initial seed data:
|
|
|
|
| Code | Name | Native Name | Sort Order |
|
|
|------|------|-------------|------------|
|
|
| fi | Finnish | Suomi | 1 |
|
|
| en | English | English | 2 |
|
|
| sv | Swedish | Svenska | 3 |
|
|
| no | Norwegian | Norsk | 4 |
|
|
| de | German | Deutsch | 5 |
|
|
| ru | Russian | Русский | 6 |
|
|
|
|
|
|
Language codes are fixed because translations are stored in columns on `entries`. The `supported_languages` table controls labels, ordering, and whether a language is active. To add a language, you must add a new column to `entries` and add a corresponding row to `supported_languages`.
|
|
|
|
### Entry
|
|
An entry represents a translatable unit which may be:
|
|
|
|
- `word` — Single word
|
|
- `phrase` — Multi-word expression or idiom, sentence
|
|
- `proper_name` — Person's name (for consistent transliteration)
|
|
- `title` — Book, publication, or hymn title
|
|
- `reference` — Biblical or doctrinal term
|
|
- `other` — Any other translatable text unit
|
|
|
|
Each entry has translations in multiple languages.
|
|
|
|
### Suggested Meaning
|
|
When translators disagree on a translation or want to suggest alternatives (regional variations, contextual meanings, etc.), they can submit a suggested meaning for community review.
|
|
|
|
---
|
|
|
|
## Technical Stack
|
|
|
|
* Framework: Rails 8
|
|
* Database: SQLite with FTS5
|
|
* Authentication: Rails 8 built-in authentication
|
|
* Authorization: Invitation-only for contributors
|
|
* Deployment: Kamal
|
|
|
|
---
|
|
|
|
## Setup / First User
|
|
|
|
When setup has not been completed, the `/setup` route is accessible for creating the initial admin account. Completion is tracked in the database. The first user created will be the system's default contact email (accessible via `User.first.email`).
|
|
|
|
For detailed setup instructions, see [SETUP_GUIDE.md](docs/SETUP_GUIDE.md).
|
|
|
|
**Quick Start:**
|
|
1. Deploy the application
|
|
2. Navigate to `/setup`
|
|
3. Create your admin account
|
|
4. Start inviting contributors
|
|
|
|
---
|
|
|
|
## Authentication Flow
|
|
|
|
### Public Access
|
|
- No authentication required for browsing and searching entries
|
|
- Read-only access to all dictionary content
|
|
|
|
### Invitation-Only Registration
|
|
- Admins send email invitations with unique tokens
|
|
- Invited users register by setting name and password
|
|
- `invitation_token` cleared after successful registration
|
|
|
|
### Login & Sessions
|
|
- Email + password authentication
|
|
- Session-based (encrypted cookies, Rails default)
|
|
- Optional "remember me" for extended sessions
|
|
|
|
### Authorization
|
|
- **Contributor**: Create/edit entries, add comments, suggest translations
|
|
- **Reviewer**: All contributor actions + review suggestions, verify entries
|
|
- **Admin**: All actions + invite users, manage roles
|
|
|
|
### Security
|
|
- Passwords hashed with bcrypt
|
|
- Rate limiting on login attempts
|
|
- Invitation tokens expire after 14 days
|
|
|
|
---
|
|
|
|
## Database Schema
|
|
|
|
see `db/structure.sql`
|
|
|
|
---
|
|
|
|
## Initial Data
|
|
|
|
See 'public/Kristillisyyden sanasto ver 23.5.2013.xlsx'
|
|
|
|
---
|
|
|
|
## User Roles & Permissions
|
|
|
|
| Action | Public | Contributor | Reviewer | Admin |
|
|
|--------|--------|-------------|----------|-------|
|
|
| View entries | ✓ | ✓ | ✓ | ✓ |
|
|
| Search entries | ✓ | ✓ | ✓ | ✓ |
|
|
| Create entry | | ✓ | ✓ | ✓ |
|
|
| Edit entry | | ✓ | ✓ | ✓ |
|
|
| Add comment | | ✓ | ✓ | ✓ |
|
|
| Submit suggested meaning | | ✓ | ✓ | ✓ |
|
|
| Review suggested meanings | | | ✓ | ✓ |
|
|
| Mark entry as verified | | | ✓ | ✓ |
|
|
| Invite new users | | | | ✓ |
|
|
| Manage users | | | | ✓ |
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
### Public Features
|
|
|
|
**Search & Browse**
|
|
- Full-text search across all languages
|
|
- Filter by category
|
|
- Alphabetical browsing per language
|
|
- View entry with all translations
|
|
- Download the entries table as an XLSX file, without :id attribute
|
|
|
|
### Contributor Features
|
|
|
|
**Entry Management**
|
|
- Create new entries with translations in known languages
|
|
- Edit existing translations
|
|
- Leave empty translations for others to fill in
|
|
- Add notes/context to entries
|
|
- View edit history
|
|
|
|
**Discussion**
|
|
- Add comments to entries
|
|
- Submit alternative translations as suggested meanings
|
|
- Participate in translation discussions
|
|
|
|
### Reviewer Features
|
|
|
|
**Quality Control**
|
|
- Review and approve/reject suggested meanings
|
|
- Mark entries as verified
|
|
- Merge duplicate entries
|
|
|
|
### Admin Features
|
|
|
|
**User Management**
|
|
- Send invitations via email
|
|
- Assign/change user roles
|
|
- Deactivate users
|
|
|
|
**System Management**
|
|
- Bulk import/export (CSV)
|
|
- Database backup
|
|
|
|
---
|
|
|
|
## User Interface
|
|
|
|
### Pages
|
|
|
|
1. **Home/Search** — Search box, quick stats, recent entries
|
|
2. **Browse** — Alphabetical listing with language selection
|
|
3. **Entry View** — Single entry with all translations, comments, suggested meanings
|
|
4. **Entry Edit** — Form for editing translations (contributors only)
|
|
5. **New Entry** — Form for creating entries (contributors only)
|
|
6. **Suggested Meanings Queue** — List for reviewers
|
|
7. **User Profile** — Personal settings, contribution history
|
|
8. **Admin Dashboard** — User management, invitations, stats
|
|
|
|
### Design Principles
|
|
- Clean, readable typography (translations must be easy to read quickly)
|
|
- Mobile-friendly (translators may use during services)
|
|
- Fast search (primary use case)
|
|
- Clear visual distinction between verified and unverified entries
|
|
|
|
---
|
|
|
|
## API (Public Sync)
|
|
|
|
Public JSON endpoint for syncing entries:
|
|
```
|
|
GET /api/entries
|
|
GET /api/entries?since=2026-01-01T12:00:00Z
|
|
```
|
|
|
|
Responses include all language columns, category and `updated_at`. The optional `since`
|
|
parameter filters by `updated_at` (ISO8601).
|
|
|
|
Swagger docs:
|
|
```
|
|
GET /api/swagger
|
|
```
|
|
|
|
Swagger UI:
|
|
```
|
|
GET /api
|
|
```
|
|
|
|
## Deployment
|
|
|
|
Server: Single VPS with Kamal
|
|
Database: SQLite with Litestream for replication/backup
|
|
Assets: Propshaft (Rails 8 default)
|
|
Background Jobs: Solid Queue (for invitation emails)
|
|
|
|
|
|
## Future Considerations
|
|
|
|
Export to PDF/print format for offline use
|
|
Audio pronunciation recordings
|
|
Mobile app
|
|
Offline mode with sync
|
|
Additional languages via migration
|