@rglabs/butterfly 2.0.1

package/docs/translations.md

@@ -0,0 +1,346 @@
+# Translations and Internationalization
+
+Butterfly CMS includes a built-in translation system for managing multilingual content in the admin interface. This guide covers how translations work and how to manage them.
+
+## Overview
+
+The translation system consists of three main tables:
+
+| Table | Purpose |
+|-------|---------|
+| `bfy_languages` | Defines available languages (e.g., English, Turkish, German) |
+| `bfy_translation_texts` | Stores source texts (original strings to be translated) |
+| `bfy_translations` | Stores translated texts, linking languages to source texts |
+
+## Database Schema
+
+### bfy_languages
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | int | Primary key |
+| `name` | string | Language name (e.g., "English", "Turkish") |
+| `iso_code` | string | ISO language code (e.g., "en", "tr") |
+| `translations` | custom | Virtual field - renders the Translation Manager UI |
+
+### bfy_translation_texts
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | int | Primary key |
+| `source` | text | The original text to be translated |
+
+### bfy_translations
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | int | Primary key |
+| `bfy_language_id` | int | Reference to `bfy_languages` |
+| `bfy_translation_text_id` | int | Reference to `bfy_translation_texts` |
+| `text` | text | The translated text |
+
+## How It Works
+
+1. **Source texts** are stored in `bfy_translation_texts` - these are the original strings that need translation
+2. **Languages** are defined in `bfy_languages` - each language you want to support
+3. **Translations** link source texts to their translated versions in each language via `bfy_translations`
+
+### Translation Manager UI
+
+When editing a language in `bfy_languages`, the `translations` custom field displays an interactive Translation Manager with:
+
+- **Statistics**: Total strings, translated count, pending count
+- **Search & Filter**: Search translations or filter by status (translated/untranslated)
+- **Manual Entry**: Edit individual translations inline
+
+## CLI Translation Command
+
+The `butterfly-cli translate` command provides efficient operations for managing translations without needing to read YAML files.
+
+### Operations
+
+| Operation | Description |
+|-----------|-------------|
+| `languages` | List all languages with translation statistics |
+| `get-untranslated` | Get untranslated texts for a language |
+| `add` | Add or update a single translation |
+| `bulk` | Bulk add/update translations from JSON file |
+
+### List Languages
+
+```bash
+# List all languages with translation stats (table format)
+butterfly-cli translate languages
+
+# Output as JSON
+butterfly-cli translate languages --format json
+```
+
+**Example output:**
+```
+ID  | ISO | Name         | Translated  | Untranslated
+------------------------------------------------------------
+1   | en  | English      | 450/600     | 150
+2   | tr  | Turkish      | 580/600     | 20
+3   | de  | German       | 200/600     | 400
+```
+
+### Get Untranslated Texts
+
+```bash
+# Get all untranslated texts for Turkish
+butterfly-cli translate get-untranslated --lang tr
+
+# Get first 50 untranslated texts
+butterfly-cli translate get-untranslated --lang tr --limit 50
+
+# Get untranslated as JSON (for processing)
+butterfly-cli translate get-untranslated --lang tr --format json
+
+# Use language ID instead of ISO code
+butterfly-cli translate get-untranslated --lang-id 2
+```
+
+### Add Single Translation
+
+```bash
+# Add translation by source text
+butterfly-cli translate add --lang tr --source "Welcome" --text "Hoş geldiniz"
+
+# Add translation by source ID
+butterfly-cli translate add --lang tr --source-id 123 --text "Hoş geldiniz"
+
+# Using language ID
+butterfly-cli translate add --lang-id 2 --source "Save" --text "Kaydet"
+```
+
+**Note:** The `add` command automatically detects if a translation exists and updates it instead of creating a duplicate.
+
+### Bulk Translation
+
+Create a CSV file with tab-delimited columns (source and text):
+
+```
+source	text
+Welcome	Hoş geldiniz
+Save	Kaydet
+Cancel	İptal
+Delete	Sil
+Hello, World!	Merhaba, Dünya!
+```
+
+> **Note:** Use TAB character as delimiter (not comma) to handle text containing commas. The header row is optional.
+
+Then run:
+
+```bash
+# Bulk translate from file
+butterfly-cli translate bulk --lang tr --file translations.csv
+
+# Using language ID
+butterfly-cli translate bulk --lang-id 2 --file translations.csv
+```
+
+**Bulk command behavior:**
+- Creates missing source texts automatically
+- Updates existing translations
+- Creates new translations for untranslated texts
+- Handles quoted fields with embedded tabs or newlines
+- Reports summary with counts of added/updated/skipped/errors
+
+### Options Reference
+
+| Option | Description |
+|--------|-------------|
+| `--lang <iso_code>` | Language ISO code (e.g., `tr`, `de`, `en`) |
+| `--lang-id <id>` | Language ID (alternative to `--lang`) |
+| `--source <text>` | Source text to translate |
+| `--source-id <id>` | Source text ID (alternative to `--source`) |
+| `--text <translation>` | Translated text (for `add` operation) |
+| `-f, --file <path>` | CSV file path (tab-delimited) for `bulk` operation |
+| `--format <format>` | Output format: `json` or `table` (default: `table`) |
+| `--limit <count>` | Limit number of results |
+
+## Claude Code Translation Workflow (Recommended)
+
+> **AI INSTRUCTION:** Use the `butterfly-cli translate` command for efficient translation operations. This eliminates the need to read YAML files and handles all edge cases automatically.
+
+### Step 1: List Languages and Check Status
+
+```bash
+butterfly-cli translate languages
+```
+
+### Step 2: Get Untranslated Texts
+
+```bash
+# Get untranslated texts as JSON for a language
+butterfly-cli translate get-untranslated --lang tr --format json --limit 100
+```
+
+### Step 3: Add Translations
+
+**For single translations:**
+```bash
+butterfly-cli translate add --lang tr --source "Welcome" --text "Hoş geldiniz"
+```
+
+**For bulk translations:** Create a tab-delimited CSV file and use:
+```bash
+butterfly-cli translate bulk --lang tr --file translations.csv
+```
+
+### Complete Example Workflow
+
+```bash
+# 1. Check which languages need translations
+butterfly-cli translate languages
+
+# 2. Get untranslated texts for Turkish (first 20)
+butterfly-cli translate get-untranslated --lang tr --limit 20 --format json > untranslated.json
+
+# 3. After translating, create translations.csv (tab-delimited):
+# source	text
+# Original	Translated
+
+# 4. Bulk import translations
+butterfly-cli translate bulk --lang tr --file translations.csv
+```
+
+## Managing Translations (Alternative Methods)
+
+### Adding a New Language
+
+```bash
+butterfly-cli record add bfy_languages --data '{
+  "name": "German",
+  "iso_code": "de"
+}'
+```
+
+### Adding Source Texts Manually
+
+Source texts are typically added automatically by the system. To add manually:
+
+```bash
+butterfly-cli record add bfy_translation_texts --data '{
+  "source": "Welcome to the application"
+}'
+```
+
+### Using Record Command (Low-Level)
+
+For direct database operations when needed:
+
+```bash
+# Add a translation
+butterfly-cli record add bfy_translations --data '{
+  "bfy_language_id": 2,
+  "bfy_translation_text_id": 1,
+  "text": "Willkommen bei der Anwendung"
+}'
+
+# Update an existing translation
+butterfly-cli record edit bfy_translations --id 123 --data '{
+  "text": "Updated translation text"
+}'
+```
+
+## Using Translations in Twig
+
+### Fetching Translations for a Language
+
+```twig
+{# Get all translations for a specific language as key-value pairs #}
+{% set translations = db()
+    .from('bfy_translations')
+    .where('bfy_language_id', languageId)
+    .keyToValue('bfy_translation_text_id', 'text')
+%}
+
+{# Access: translations[textId] returns the translated text #}
+```
+
+### Fetching Source Texts
+
+```twig
+{% set sourceTexts = db()
+    .from('bfy_translation_texts')
+    .get()
+%}
+```
+
+### Finding Untranslated Texts
+
+```twig
+{% set texts = db().from('bfy_translation_texts').get() %}
+{% set translations = db()
+    .from('bfy_translations')
+    .where('bfy_language_id', languageId)
+    .keyToValue('bfy_translation_text_id', 'text')
+%}
+
+{% set untranslated = [] %}
+{% for text in texts %}
+    {% if not translations[text.id] %}
+        {% set untranslated = untranslated|merge([text]) %}
+    {% endif %}
+{% endfor %}
+```
+
+## Related Tables
+
+### language_settings
+
+A separate table for frontend/site language configuration:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `lang_key` | string | Language key (e.g., "en", "tr") |
+| `name` | string | Display name |
+| `image` | string | Flag/icon image |
+
+> **Note:** `language_settings` is for site/frontend language selection, while `bfy_languages` is for admin interface translations.
+
+## Download/Upload (YAML Files)
+
+For working with YAML translation files, use the standard `download` and `upload` commands.
+
+### Download Translations
+
+```bash
+# Download all resources (includes translations)
+butterfly-cli download
+
+# Download only translations
+butterfly-cli download -t translations
+```
+
+This creates YAML files in `butterfly-resources/translations/` (one file per language).
+
+### Upload Translations
+
+```bash
+# Upload a specific language file
+butterfly-cli upload ./butterfly-resources/translations/tr.yaml
+
+# Upload all translation files
+butterfly-cli upload ./butterfly-resources/translations/
+```
+
+### YAML File Format
+
+```yaml
+"Welcome": "Hoş geldiniz"
+"Save": "Kaydet"
+"Cancel": "İptal"
+"Delete": ""           # Empty = not yet translated
+```
+
+## Best Practices
+
+1. **Use `translate` command**: Prefer `butterfly-cli translate` over reading YAML files for AI workflows
+2. **Bulk operations**: Use `translate bulk` for multiple translations in one operation
+3. **Check status first**: Always run `translate languages` to see translation progress
+4. **ISO codes**: Use standard ISO 639-1 codes (e.g., `tr`, `de`, `en`)
+5. **Auto-upsert**: The `translate add` command automatically updates existing translations

package/docs/twig-helpers.md

@@ -0,0 +1,283 @@
+# Twig Helper Functions Reference
+
+Reference for database queries, CRUD operations, and helper functions available in Butterfly Twig code.
+
+## Database Queries (db)
+
+### Basic Query
+
+```twig
+{% set records = db()
+    .table('table_name')
+    .get()
+%}
+```
+
+### With Different Database
+
+```twig
+{% set records = db('database_alias')
+    .table('table_name')
+    .get()
+%}
+```
+
+### Without Authentication (for webservices)
+
+```twig
+{% set records = db('default', false)
+    .table('table_name')
+    .get()
+%}
+```
+
+## Query Methods
+
+### Select Specific Columns
+
+```twig
+{% set records = db()
+    .table('users')
+    .select('id', 'name', 'email')
+    .get()
+%}
+```
+
+### Where Conditions
+
+```twig
+{# Basic where #}
+.where('status', 'active')
+
+{# With operator #}
+.where('price', '>', 100)
+
+{# Multiple conditions #}
+.where('status', 'active')
+.where('category_id', 5)
+
+{# Or where #}
+.orWhere('status', 'pending')
+
+{# Where in array #}
+.whereIn('id', [1, 2, 3])
+
+{# Where null #}
+.whereNull('deleted_at')
+
+{# Where not null #}
+.whereNotNull('email')
+```
+
+### Joins
+
+```twig
+{% set records = db()
+    .table('orders')
+    .join('users', 'users.id', '=', 'orders.user_id')
+    .select('orders.*', 'users.name as user_name')
+    .get()
+%}
+
+{# Left join #}
+.leftJoin('categories', 'categories.id', '=', 'products.category_id')
+```
+
+### Ordering
+
+```twig
+{# Ascending #}
+.orderBy('created_at')
+
+{# Descending #}
+.orderByDesc('created_at')
+```
+
+> **Note:** Use `orderByDesc('column')` instead of `orderBy('column', 'DESC')`.
+
+### Limiting
+
+```twig
+.limit(10)
+.offset(20)
+```
+
+### Grouping
+
+```twig
+.groupBy('category_id')
+```
+
+## Result Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `.get()` | array | All matching records |
+| `.first()` | object/null | First matching record |
+| `.count()` | integer | Count of matching records |
+| `.sum('column')` | number | Sum of column values |
+| `.avg('column')` | number | Average of column values |
+| `.max('column')` | mixed | Maximum value |
+| `.min('column')` | mixed | Minimum value |
+
+### Examples
+
+```twig
+{% set users = db().table('users').where('is_active', 1).get() %}
+{% set user = db().table('users').where('id', 5).first() %}
+{% set total = db().table('orders').where('user_id', 5).count() %}
+{% set sum = db().table('order_items').sum('total') %}
+```
+
+## Data Extraction Methods
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `column('col')` | Array of single column values | `[1, 2, 3]` |
+| `keyToValue('key', 'val')` | Map key to value | `{1: "John", 2: "Jane"}` |
+| `keyToValue('key')` | Map key to full row | `{1: {id: 1, name: "John"}}` |
+| `keyToValues('key', 'val')` | Map key to array of values | `{1: [100, 200], 2: [150]}` |
+| `keyToValues('key')` | Map key to array of rows | `{1: [{...}, {...}]}` |
+
+### Examples
+
+```twig
+{# Get array of IDs #}
+{% set ids = db().table('users').column('id') %}
+{# Result: [1, 2, 3] #}
+
+{# Get id => name mapping #}
+{% set userNames = db().table('users').keyToValue('id', 'name') %}
+{# Result: {1: "John", 2: "Jane"} #}
+
+{# Get id => full record mapping #}
+{% set usersById = db().table('users').keyToValue('id') %}
+{# Result: {1: {id: 1, name: "John", ...}} #}
+
+{# Get user_id => order totals (multiple per user) #}
+{% set ordersByUser = db().table('orders').keyToValues('user_id', 'total') %}
+{# Result: {1: [100, 200], 2: [150]} #}
+```
+
+> **Note:** There is no `pluck()` method. Use `column()` instead.
+
+## CRUD Operations
+
+### Insert
+
+```twig
+{% set response = crud()
+    .table('users')
+    .insert({
+      "name": "John",
+      "email": "john@example.com"
+    })
+%}
+
+{% if response.success %}
+    New ID: {{ response.id }}
+{% else %}
+    Error: {{ response.message }}
+{% endif %}
+```
+
+### Update
+
+```twig
+{% set response = crud()
+    .table('users')
+    .update({
+      "id": 5,
+      "name": "John Updated"
+    })
+%}
+```
+
+### Delete
+
+```twig
+{% set response = crud()
+    .table('users')
+    .delete({
+      "id": 5
+    })
+%}
+```
+
+### Without Authentication (for webservices)
+
+```twig
+{% set response = crud('default', false)
+    .table('submissions')
+    .insert({...})
+%}
+```
+
+## Object Spec Helper Functions
+
+Functions available in `processing_code` and `template_code`:
+
+| Function | Context | Description |
+|----------|---------|-------------|
+| `getValue('column')` | processing_code | Get current record field value |
+| `setValue('column', value)` | processing_code | Set field value |
+| `errorMessage('msg')` | processing_code | Show error and stop processing |
+| `getParameter('name')` | both | Get POST/GET parameter |
+| `currentUser('field')` | both | Get current user info |
+| `info.column` | template_code | Access current record data |
+
+### Examples
+
+```twig
+{# In processing_code #}
+{% set status = getValue('status') %}
+{{ setValue('updated_at', 'now'|date('Y-m-d H:i:s')) }}
+{{ errorMessage('Validation failed') }}
+
+{# Get request parameter #}
+{% set action = getParameter('action') %}
+
+{# Get current user #}
+{% set userId = currentUser('id') %}
+{% set userEmail = currentUser('email') %}
+
+{# In template_code #}
+{{ info.title }}
+{{ info.status }}
+```
+
+## Settings
+
+Retrieve application settings stored in `cms_setting_groups` and `cms_settings` tables.
+
+```twig
+{# Get a single setting value #}
+{% set apiKey = setting('payment', 'api_key') %}
+
+{# Get all settings in a group (returns object with alias => row mapping) #}
+{% set paymentSettings = setting('payment') %}
+{{ paymentSettings.api_key.value }}
+{{ paymentSettings.secret_key.value }}
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `group` | The `alias` from `cms_setting_groups` |
+| `setting` | (Optional) The `alias` from `cms_settings` |
+
+**Returns:** When `setting` is provided, returns the `value` field. When omitted, returns all settings in the group as `{alias: {value, val_1, val_2, ...}}`.
+
+## Important Notes
+
+1. **Integer indexes don't work in Twig arrays.** Use string prefixes:
+   ```twig
+   {# Wrong #}
+   {% set data = {0: 'a', 1: 'b'} %}
+
+   {# Correct #}
+   {% set data = {'item_0': 'a', 'item_1': 'b'} %}
+   ```
+
+2. **Cannot query multiple databases in single query.** Use separate queries.
+
+3. **Error checking:** Always check `.butterfly/error_log.txt` for Twig errors.