Introduction

When developing Omeka S themes, information about implementing multilingual support is limited. This article explains the specific steps for making an Omeka S custom theme multilingual, along with important notes for implementation.

Table of Contents

  1. How the Omeka S Translation System Works
  2. Files Needed for Theme Multilingual Support
  3. Step-by-Step Guide
  4. Common Mistakes and Solutions
  5. Implementation Examples
  6. Troubleshooting

1. How the Omeka S Translation System Works

Omeka S uses the gettext standard translation system. In this system:

  • .po files: Human-readable translation source files
  • .mo files: Compiled binary files (actually used at runtime)
  • $translate() function: Applies translations within PHP templates

2. Files Needed for Theme Multilingual Support

Required Directory Structure

your-theme/
├── config/
│   └── theme.ini          # Important: add has_translations = "true"
├── language/
│   ├── template.pot       # Translation template (optional)
│   ├── ja.po             # Japanese translation source
│   └── ja.mo             # Japanese translation binary
└── view/
    └── (various template files)

3. Step-by-Step Guide

Step 1: Configuring theme.ini

Add the following line to the [info] section of the config/theme.ini file:

[info]
name = "Your Theme Name"
version = "1.0.0"
author = "Your Name"
description = "Theme description"
omeka_version_constraint = "^4.1.0"
has_translations = "true"  # <- This line is important!

Important: Without has_translations = "true", translation files will not be loaded.

Step 2: Creating Translation Files

2.1 Creating the PO File

Create language/ja.po:

msgid ""
msgstr ""
"Project-Id-Version: Your Theme Name\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2025-01-13 12:00+0900\n"
"PO-Revision-Date: 2025-01-13 12:00+0900\n"
"Last-Translator: Your Name\n"
"Language-Team: Japanese\n"
"Language: ja\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=1; plural=0;\n"

# Navigation
msgid "Home"
msgstr "ホーム"

msgid "Browse"
msgstr "閲覧"

msgid "Search"
msgstr "検索"

# Search results
msgid "No Results Found"
msgstr "検索結果がありません"

msgid "%1$d %2$s"
msgstr "%1$d%2$s"

msgid "items"
msgstr "件のアイテム"

2.2 Compiling the MO File

Compile the PO file into an MO file:

# Install the msgfmt command (if needed)
# Mac: brew install gettext
# Ubuntu/Debian: sudo apt-get install gettext
# CentOS/RHEL: sudo yum install gettext

# Compile
msgfmt -o language/ja.mo language/ja.po

Step 3: Using Translations in Templates

Usage in PHP Templates

php
// Basic usage
echo $this->translate('Search');

// Using with a variable
$translate = $this->plugin('translate');
echo $translate('Search');

// Usage with sprintf format
echo sprintf($translate('%1$d %2$s'), $count, $translate('items'));
?>

Implementation Example

view/search/results-header-footer.phtml -->
div class="btn-group">
    button type="button" aria-label="$translate('Grid view') ?>">
        span> $translate('Grid') ?>span>
    button>
    button type="button" aria-label="$translate('List view') ?>">
        span> $translate('List') ?>span>
    button>
div>

4. Common Mistakes and Solutions

Mistake 1: Creating Module.php

// Unnecessary! Not needed for themes
class Module extends AbstractModule { ... }

Solution: Module.php is not needed for themes. has_translations = "true" alone is sufficient.

Mistake 2: Case Mismatch

// PO file
msgid "Grid"
msgstr "グリッド"

// PHP template
 $translate('grid') ?>  // Does not work!

Solution: Translation keys are case-sensitive. They must match exactly.

Mistake 3: Incorrect Language Code

# Incorrect
language/ja_JP.po  # Omeka S may not recognize ja_JP

# Correct
language/ja.po     # Use a simple language code

5. Implementation Examples

Multilingual Language Badge Display

php
// Convert language codes to language names
$languageNames = [
    'en' => $translate('English'),
    'ja' => $translate('Japanese'),
    'fr' => $translate('French'),
    'de' => $translate('German'),
    'es' => $translate('Spanish'),
];

$languageDisplay = isset($languageNames[$valueLang])
    ? $languageNames[$valueLang]
    : strtoupper($valueLang);
?>
span class="badge bg-secondary"> $escape($languageDisplay) ?>span>

Displaying Item Count

php
// "7 items" -> "7件のアイテム"
$count = 7;
$label = $translate('items');
echo sprintf($translate('%1$d %2$s'), $count, $label);
?>

6. Troubleshooting

Checklist When Translations Are Not Applied

  1. Check theme.ini
grep "has_translations" config/theme.ini
# Output: has_translations = "true"
  1. Check MO file
file language/ja.mo
# Output: GNU message catalog...

  1. Clear cache

    • Browser: Ctrl+Shift+R (Windows/Linux), Cmd+Shift+R (Mac)
    • When using Docker: restart the container
docker-compose restart

  1. Check language settings

    • Omeka S admin panel -> Site settings -> Set language to “Japanese”
    • User settings -> Set language to “Japanese”

Debugging Methods

// Check the current language
php echo $this->lang(); ?>

// Check if translation is working
php
$test = $this->translate('Test');
echo "Original: Test, Translated: $test";
?>

Summary

Multilingual support for Omeka S themes can be achieved in three steps:

  1. Add has_translations = "true" to theme.ini
  2. Place translation files in the language/ directory
  3. Use the $translate() function in templates

Module.php and module.config.php are not required, and multilingual support can be achieved with simple configuration.

References

This article was created based on actual Omeka S theme development experience. Verified to work with version 4.1.0.