Internationalization with Laravel's Translation

[pronist]

Hello! While attempting to create a static site with Jigsaw, I spent a lot of time thinking about internationalization, and I'd like to share the approach I used.

Installation

mkdir my-app
cd my-app

composer require tightenco/jigsaw

vendor/bin/jigsaw init
npm install

Internationalization

We use Laravel Translation for internationalization.

composer require illuminate/translation

Since we will be creating a dedicated class for handling internationalization, add PSR-4 to composer.json.

"autoload": {
    "psr-4": {
        "App\\": "app"
    }
}

Create an app directory for the classes.

mkdir app

composer dump-autoload

Now let's create the I18n class for internationalization and the lang directory for storing language settings.

touch app/I18n.php

mkdir lang

I18n

The I18n class is responsible for internationalization, retrieving values for specific keys from the language files. It also facilitates translation with I18n::trans().

<?php

namespace App;

use Illuminate\Translation\Translator;
use Illuminate\Filesystem\Filesystem;
use Illuminate\Translation\FileLoader;

readonly class I18n
{
    public function __construct(private string $lang)
    {
    }

    public function trans(string $key): string
    {
        $loader = new FileLoader(
            new Filesystem(),
            dirname(__DIR__) . '/lang'
        );

        $translator = new Translator($loader, $this->lang);

        return $translator->get($key);
    }
}

helpers.php

For convenience, let's create a trans() function in helpers.php. Note that trans() accesses the $page->locale variable globally or for collection pages.

touch helpers.php

<?php

use TightenCo\Jigsaw\PageVariable;
use App\I18n;

function trans(PageVariable $page, string $key): string|array
{
    $translator = new I18n($page->locale);

    return $translator->trans($key);
}

return [
    'trans' => trans(...)
];

Lang

Let's create two language files for English and Korean.

mkdir lang/en
touch lang/en/app.php

mkdir lang/ko
touch lang/ko/app.php

lang/en/app.php

<?php

return [
    'name' => 'My App',
];

lang/ko/app.php

<?php

return [
    'name' => '나의 앱',
];

Locale Collection

The LocaleCollection is a dedicated collection class for managing internationalization and locale settings. LocaleCollection::create() generates a collection for the provided locales and sets keys like locale and defaultLocale. One important note: when setting the default locale, the resulting build for the default locale does not place the collection in a separate folder. This behavior is implemented in LocaleCollection::getPath().

touch app/LocaleCollection.php

<?php

namespace App;

use Illuminate\Contracts\Support\Arrayable;
use Illuminate\Support\Collection;
use TightenCo\Jigsaw\PageVariable;

class LocaleCollection implements Arrayable
{
    use Scopeable;

    public function __construct(
        private readonly string $locale,
        private readonly string $defaultLocale,
        private readonly array $options = [],
    )
    {
    }

    public static function create(array $locales, string $defaultLocale, array $options = []): Collection
    {
        $localeCollections = collect();

        foreach ($locales as $locale) {
            $localeCollections[$locale] = new self($locale, $defaultLocale, $options)->toArray();
        }

        return $localeCollections;
    }

    public function toArray(): array
    {
        return [
            'locale' => $this->locale,
            'defaultLocale' => $this->defaultLocale,
            ...$this->options,
            'path' => $this->getPath(...),
            ...$this->getScopedCollection($this->options['map'] ?? null),
        ];
    }

    private function getPath(PageVariable $page): string
    {
        $isDefaultLocale = $page->defaultLocale === $page->locale;

        $callback = $this->options['path'] ?? null;

        $basePath = is_callable($callback)
            ? $callback($page)
            : $page->getFilename();

        $path = $this->getScopedPath($page, $basePath);

        return $isDefaultLocale ? $path : "$page->locale/$path";
    }
}

Scopeable

Scopeable is a trait that allows pages to have a scope, used for implementing nested collections. An important point in Scopeable is that Scopeable::getScopedCollection() adds variables for nested collections to the page and appends each item in the map.

<?php

namespace App;

use TightenCo\Jigsaw\Collection\CollectionItem;
use TightenCo\Jigsaw\PageVariable;

trait Scopeable
{
    private static array $scopes = [];

    private array $nestedCollection = [];

    public static function setScopes(array $scopes): void
    {
        self::$scopes = $scopes;
    }

    private function getScopedCollection(?callable $mapFunc = null): array
    {
        if (! self::$scopes) {
            return [];
        }

        foreach (self::$scopes as $scope) {
            $this->nestedCollection[$scope] = [];
        }

        $this->nestedCollection['map'] = function (CollectionItem $item) use ($mapFunc) {
            $item->scope && $this->addItemToScope($item);

            return $mapFunc ? $mapFunc($item) : CollectionItem::fromItem($item);
        };

        return $this->nestedCollection;
    }

    private function addItemToScope(CollectionItem $item): void
    {
        $item->{$item->scope}[] = $item;
    }

    private function getScopedPath(PageVariable $page, string $path): string
    {
        return $page->scope ? "$page->scope/$path" : $path;
    }
}

config.php

Now, return to the configuration and specify the collection for internationalization.

<?php

use App\LocaleCollection;

LocaleCollection::setScopes(['posts']);

return [
    'collections' => LocaleCollection::create(
        locales: ['en', 'ko'],
        defaultLocale: 'en',
    )
];

Collections

Before creating the multilingual collections and pages, let's create a layout for our example. The default index.blade.php is not needed.

touch source/_layouts/post.blade.php
rm source/index.blade.php

source/_layouts/post.blade.php

@extends('_layouts.main')

@section('body')
    {!! $page->getContent() !!}
@endsection

Create the collections and files for multilingual content.

mkdir source/_en
mkdir source/_en/index.blade.php
mkdir source/_en/posts
mkdir source/_en/posts/2024-12-01-hello.md

mkdir source/_ko
mkdir source/_ko/index.blade.php
mkdir source/_ko/posts
mkdir source/_ko/posts/2024-12-01-hello.md

source/_en/index.blade.php

Note that the index accesses the nested collection via $page->posts.

@extends('_layouts.main')

@section('body')
    <a href="/">Home</a>

    @foreach($page->posts as $post)
        <a href="{{ $post->getPath() }}">{{ $post->getFilename() }}</a>
    @endforeach
@endsection

source/_en/posts/2024-12-01-hello.md

You can add a scope setting if necessary.

---
extends: _layouts.post
scope: posts
---

Hello, world!

source/_ko/index.blade.php

@extends('_layouts.main')

@section('body')
    <a href="/">홈</a>

    @foreach($page->posts as $post)
        <a href="{{ $post->getPath() }}">{{ $post->getFilename() }}</a>
    @endforeach
@endsection

source/_ko/posts/2024-12-01-hello.md

---
extends: _layouts.post
scope: posts
---

안녕, 세계!

source/_layouts/main.blade.php

Internationalization can be handled directly in the layout.

<html lang="{{ $page->locale }}">
    <head>
        <title>{{ $page->trans('app.name') }}</title>
    </head>
</html>

Build

npm run dev

build_local/
├─ assets/
├─ ko/
│  ├─ posts/
│  │  ├─ 2024-12-01-hello/index.html
│  ├─ index.html
├─ posts/
│  ├─ 2024-12-01-hello/index.html
├─ index.html