PHPackages                             kreatif/translum - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. kreatif/translum

ActiveLibrary[Utility & Helpers](/categories/utility)

kreatif/translum
================

v0.1.2(2mo ago)1167[1 issues](https://github.com/kreatifIT/translum/issues)MITPHP

Since Aug 11Pushed 2mo agoCompare

[ Source](https://github.com/kreatifIT/translum)[ Packagist](https://packagist.org/packages/kreatif/translum)[ RSS](/packages/kreatif-translum/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (4)Versions (11)Used By (0)

Translum - Advanced Translation Manager for Statamic
====================================================

[](#translum---advanced-translation-manager-for-statamic)

A powerful and feature-rich translation management package for Statamic CMS that allows clients to edit file-based translations directly from the Control Panel.

Features
--------

[](#features)

- **Control Panel Interface** - User-friendly interface for managing translations
- **Pagination** - Load translations in chunks for better performance with large files
- **Search & Filter** - Real-time search across translation keys and values
- **File Filtering** - Include/exclude specific translation files with wildcard support
- **Vendor Translations** - Support for vendor package translations
- **Caching** - Intelligent caching layer for improved performance
- **Artisan Commands** - Powerful CLI tools for translation management
- **Multiple Field Types** - Support for text, Bard, and other field types
- **Multi-locale Support** - Edit translations for all configured Statamic locales

Installation
------------

[](#installation)

Install via Composer:

```
composer require kreatif/translum
```

Publish the configuration file:

```
php artisan vendor:publish --tag=translum-config
```

Configuration
-------------

[](#configuration)

The configuration file is published to `config/statamic/translum.php`.

### Basic Configuration

[](#basic-configuration)

```
return [
    // Field type for translation inputs
    'field_type' => 'bard', // or 'text'

    // Pagination settings
    'pagination' => [
        'enabled' => true,
        'per_page' => 50,
    ],

    // Search functionality
    'search' => [
        'enabled' => true,
        'search_in_values' => true,
        'case_sensitive' => false,
    ],
];
```

### File Filtering

[](#file-filtering)

Control which translation files appear in the Control Panel:

```
'file_filter' => [
    'mode' => 'include', // Options: 'all', 'include', 'exclude'
    'patterns' => [
        'messages',      // Exact match
        'validation',    // Exact match
        'custom/*',      // Wildcard match
    ],
],
```

**Modes:**

- `all` - Load all translation files (default)
- `include` - Only load specified files
- `exclude` - Load all except specified files

### Vendor Translations

[](#vendor-translations)

Enable editing of vendor package translations:

```
'vendor_translations' => [
    'enabled' => true,
    'packages' => [
        'statamic',
        'laravel-backup',
        // Add more vendor packages
    ],
],
```

Leave `packages` empty to load all vendor translations.

### Performance Settings

[](#performance-settings)

```
'cache' => [
    'enabled' => true,
    'ttl' => 3600, // Cache for 1 hour
    'key_prefix' => 'translum',
],

'performance' => [
    'lazy_load_tabs' => true,
    'chunk_size' => 100,
],
```

### Cache Clearing on Save

[](#cache-clearing-on-save)

Control which caches are cleared when translations are saved (fixes cached views issue):

```
'clear_caches_on_save' => [
    'view_cache' => true,        // Clear compiled views (fixes cached translations in views)
    'translator_cache' => true,  // Clear Laravel translator cache
    'application_cache' => false, // Clear application cache (optional)
    'config_cache' => false,     // Clear config cache (usually not needed)
],
```

**Important for Production/Staging:**

- `view_cache` should be `true` to ensure translation changes appear immediately
- `translator_cache` should be `true` to refresh Laravel's translation loader
- `application_cache` can be `false` to avoid clearing other cached data

Permissions
-----------

[](#permissions)

Translum includes granular permission controls for the Statamic Control Panel.

### Available Permissions

[](#available-permissions)

- **Edit Translations** - Main permission to access and edit translations
    - View Translation Statistics - View stats and information
    - Export Translations - Export to JSON/CSV
    - Clear Translation Cache - Clear the cache

### Setting Up Permissions

[](#setting-up-permissions)

1. Go to **Users > User Groups** in your Statamic CP
2. Edit a user group or create a new one
3. Under permissions, find "Translum" section
4. Check "Edit Translations" to grant access
5. Optionally grant sub-permissions for stats, export, and cache clearing

Only users with the "Edit Translations" permission will see the Translations menu item and can access the translation editor.

Usage
-----

[](#usage)

### Control Panel

[](#control-panel)

After installation, a "Translations" menu item will appear in your Statamic Control Panel navigation (if you have permission).

1. Click "Translations" in the CP nav
2. Select a file tab to view translations
3. Edit translations for each locale
4. Use the search bar to filter translations
5. Navigate through pages if pagination is enabled
6. Click "Save" to persist changes

### Query Parameters

[](#query-parameters)

You can use URL query parameters to filter the translation view:

- `?search=welcome` - Search for translations containing "welcome"
- `?page=2` - Go to page 2 (when pagination is enabled)
- `?search=password&page=1` - Combine search and pagination

Artisan Commands
----------------

[](#artisan-commands)

### List Translations

[](#list-translations)

Display all translation files and statistics:

```
php artisan translum:list
```

Filter by file:

```
php artisan translum:list --file=messages
```

Search for specific keys:

```
php artisan translum:list --search=password
```

### Translation Statistics

[](#translation-statistics)

View comprehensive statistics about your translations:

```
php artisan translum:stats
```

Shows:

- Number of locales and files
- Translation keys per file
- Missing translations highlighted
- Cache status

### Sync Translations

[](#sync-translations)

Add missing translation keys across all locales:

```
php artisan translum:sync
```

This command finds keys that exist in one locale but are missing in others and creates them with empty values.

Options:

```
# Sync specific locale only
php artisan translum:sync --locale=de

# Preview changes without making them
php artisan translum:sync --dry-run
```

### Export Translations

[](#export-translations)

Export translations to JSON or CSV format:

```
# Export to JSON
php artisan translum:export --format=json

# Export to CSV
php artisan translum:export --format=csv

# Export specific file
php artisan translum:export --file=messages --format=json

# Custom output path
php artisan translum:export --format=json --output=/path/to/export.json
```

### Clear Cache

[](#clear-cache)

Clear the Translum translation cache:

```
php artisan translum:clear-cache
```

Cache is automatically cleared when translations are saved through the Control Panel.

API Endpoints
-------------

[](#api-endpoints)

### Search Endpoint

[](#search-endpoint)

Search translations via AJAX:

```
GET /cp/translum/search?q=password&file=messages

```

Response:

```
{
    "results": [
        {
            "file": "messages",
            "key": "reset_password",
            "values": {
                "en": "Reset Password",
                "de": "Passwort zurücksetzen"
            }
        }
    ],
    "count": 1
}
```

### Stats Endpoint

[](#stats-endpoint)

Get translation statistics:

```
GET /cp/translum/stats

```

Response:

```
{
    "locales": ["en", "de", "fr"],
    "locales_count": 3,
    "files": ["messages", "validation", "auth"],
    "files_count": 3,
    "total_keys": 150,
    "cache_enabled": true,
    "pagination_enabled": true,
    "per_page": 50
}
```

Performance Optimization
------------------------

[](#performance-optimization)

### For Large Translation Files

[](#for-large-translation-files)

If you have many translations and experience slow page loads:

1. **Enable Pagination** (recommended):

```
'pagination' => [
    'enabled' => true,
    'per_page' => 50, // Adjust based on your needs
],
```

2. **Enable Caching**:

```
'cache' => [
    'enabled' => true,
    'ttl' => 3600,
],
```

3. **Use File Filtering** to only load necessary files:

```
'file_filter' => [
    'mode' => 'include',
    'patterns' => ['messages', 'custom/*'],
],
```

4. **Switch to Text Field** instead of Bard for simple translations:

```
'field_type' => 'text',
```

Bard Field Configuration
------------------------

[](#bard-field-configuration)

When using Bard for rich text translations:

```
'field_type' => 'bard',
'field_config' => [
    'bard' => [
        'buttons' => [
            'bold',
            'italic',
            'link',
            'anchor',
            'removeformat',
        ],
        'remove_empty_nodes' => false,
        'smart_typography' => false,
        'save_html' => false,
    ],
],
'strip_wrapping_p' => true, // Remove wrapping  tags
```

Translation File Structure
--------------------------

[](#translation-file-structure)

Translum works with standard Laravel translation files:

```
resources/lang/
├── en/
│   ├── messages.php
│   ├── validation.php
│   └── auth.php
├── de/
│   ├── messages.php
│   ├── validation.php
│   └── auth.php
└── vendor/
    └── statamic/
        ├── en/
        │   └── messages.php
        └── de/
            └── messages.php

```

Nested arrays are automatically flattened:

```
// Original: resources/lang/en/messages.php
return [
    'user' => [
        'profile' => [
            'title' => 'Profile'
        ]
    ]
];

// Displayed in CP as:
// user.profile.title => "Profile"
```

Troubleshooting
---------------

[](#troubleshooting)

### Translations Not Updating in Views (Cached Views Issue)

[](#translations-not-updating-in-views-cached-views-issue)

**Problem:** You update translations in the CP, they're saved to the file, but your website still shows old translations.

**Cause:** Laravel compiles Blade views and caches them. The cached views contain the old translation strings.

**Solution:**

1. **Automatic (Recommended):** Enable view cache clearing in config:

```
'clear_caches_on_save' => [
    'view_cache' => true,        // Enable this!
    'translator_cache' => true,  // Enable this too!
],
```

2. **Manual:** Clear caches manually after saving:

```
php artisan view:clear
php artisan cache:clear
php artisan translum:clear-cache
```

3. **For Production/Staging Servers:**
    - Ensure `view_cache` is set to `true` in config
    - Add a deployment script to clear caches:

    ```
    php artisan optimize:clear
    php artisan translum:clear-cache
    ```

### Cache Not Clearing

[](#cache-not-clearing)

If changes still don't appear immediately after enabling cache clearing:

```
# Clear everything manually
php artisan optimize:clear
php artisan translum:clear-cache
php artisan statamic:stache:clear
```

### Missing Translations

[](#missing-translations)

Run the sync command to find and add missing keys:

```
php artisan translum:sync --dry-run
```

### Performance Issues

[](#performance-issues)

1. Enable pagination
2. Reduce `per_page` value
3. Use file filtering to load fewer files
4. Switch from Bard to text field type
5. Enable caching

### File Permissions

[](#file-permissions)

Ensure translation files are writable:

```
chmod -R 775 resources/lang
```

### Permission Denied

[](#permission-denied)

If users can't access the Translations panel:

1. Check user has "Edit Translations" permission
2. Go to Users > User Groups in CP
3. Edit the user's group
4. Enable "Edit Translations" under Translum permissions

Security
--------

[](#security)

Translation files can contain sensitive strings. Be mindful of:

- **Who has access**: Use Statamic's permission system to control access
- **What translations you expose**: Use file filtering to hide sensitive files
- **Sensitive data**: Don't store API keys or secrets in translation files

### Recommended Permission Setup

[](#recommended-permission-setup)

- **Admin Role**: Full "Edit Translations" permission
- **Editor Role**: "Edit Translations" + "View Translation Statistics"
- **Content Manager**: "Edit Translations" (without export or cache clearing)
- **Developer Role**: All permissions including export and cache clearing

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md) for recent changes.

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

Credits
-------

[](#credits)

Developed by [Kreatif](https://github.com/kreatif)

Support
-------

[](#support)

For issues, questions, or contributions:

- GitHub Issues: [Create an issue](https://github.com/kreatif/translum/issues)
- Documentation: [Full Documentation](https://github.com/kreatif/translum/wiki)

###  Health Score

33

↓

LowBetter than 72% of packages

Maintenance68

Regular maintenance activity

Popularity16

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 Bus Factor1

Top contributor holds 50% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~29 days

Recently: every ~49 days

Total

10

Last Release

60d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c58db6e153a58764dfc820c0a9d33b0a64a26b62eb8c0051912a20edb63b6499?d=identicon)[kreatif](/maintainers/kreatif)

---

Top Contributors

[![lexplatt](https://avatars.githubusercontent.com/u/743208?v=4)](https://github.com/lexplatt "lexplatt (1 commits)")[![mani-repos-link](https://avatars.githubusercontent.com/u/13603818?v=4)](https://github.com/mani-repos-link "mani-repos-link (1 commits)")

### Embed Badge

![Health badge](/badges/kreatif-translum/health.svg)

```
[![Health](https://phpackages.com/badges/kreatif-translum/health.svg)](https://phpackages.com/packages/kreatif-translum)
```

###  Alternatives

[statamic/seo-pro

68516.6k](/packages/statamic-seo-pro)[statamic-rad-pack/runway

Eloquently manage your database models in Statamic.

135224.7k7](/packages/statamic-rad-pack-runway)[rias/statamic-redirect

29335.6k](/packages/rias-statamic-redirect)[duncanmcclean/statamic-cargo

Comprehensive e-commerce addon for Statamic. Build bespoke e-commerce sites without the complexity.

3417.0k](/packages/duncanmcclean-statamic-cargo)[jacksleight/statamic-bard-texstyle

18195.4k](/packages/jacksleight-statamic-bard-texstyle)[marcorieser/statamic-livewire

A Laravel Livewire integration for Statamic.

23111.5k15](/packages/marcorieser-statamic-livewire)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)