Download the PHP package elaborate-code/jigsaw-localization without Composer
On this page you can find all versions of the php package elaborate-code/jigsaw-localization. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download elaborate-code/jigsaw-localization
More information about elaborate-code/jigsaw-localization
Files in elaborate-code/jigsaw-localization
Package jigsaw-localization
Short Description Brings localization feature to "tightenco/jigsaw" using JSON files
License MIT
Informations about the package jigsaw-localization
Jigsaw localization
This package is built on top of PHP JSON tongue to bring localization feature to tightenco/jigsaw using JSON files.
Get started
Requirements
- PHP 8.0 or higher.
Setup
Install the package using composer:
Plug LoadLocalization
to the builder by registering it in bootstrap.php
:
Simple usage
Defining Translation Strings
- Create a
lang
folder in the root of your project. - Create subfolders for each language/locale.
- Populate the subfolders with JSON files that hold translations using the
original text
as akey
, and thetranslation
as avalue
.
File structure example:
Retrieving Translation Strings
Source example:
The output:
Locale code format
two or three lowercase letters
for the language code + optionally a dash (-) with two uppercase letters
for the region code. For example, all the following codes ar
, es
, fr-CA
, haw-US
are considered valid.
The multi folder
For organizational purpose you can group internationalized translations in one JSON using many locale
keys.
greetings.json
example:
First level keys must be locale codes!
Using folder structure for locale code prefix
The default locale
First you need to define defaultLocale
in config.php
. If not set, the package will take en
as a default.
The translation helper
If you call the __
helper without providing a locale
parameter, it will try to resolve it from the page path.
If you provide the
__
helper with thelocale
parameter it will proceed with it and ignore the folder structure.
The folder structure
domain.com/{locale}/path
Pages that reside in the web root folder source
are assumed to be rendered using the defaultLocale
. Other pages that reside in subfolders named after a locale code have their locale set to the subfolder name
The included page trick
You may find your self creating a fully coded source/index.blade.php
and repeating the same code in source/fr/index.blade.php
and for other locales. To avoid that we suggest the following approach:
- Create a
source/_pages
directory which will contain the master pages. - A master page will look like any other ordinary page, _it will have the HTML structure and calls to
__
but no hardcoded$current_locale
value_ .For example You may directly copy the content ofsource/index.blade.php
tosource/_pages/index.blade.php
. - Include the master page into other pages that are locale aware.
- The included content will be able to know which locale to apply on the translation helper
__
calls as a$current_locale
.
Helpers
IMPORTANT: All the following helpers will try to resolve the locale code from the path if needed!
Setting
baseUrl
in the config is essential if your site root URL isn't 'domain.com/index.html'
current_path_locale
Returns the current page locale deduced from its path.
Usage example:
translate_path
When you have a page that is available in many locales. translate_path
helps you get the equivalent translated path
.
input/output examples:
current path | translated path | current_locale to target_locale |
---|---|---|
"/" | "/fr" | default -> fr |
"/contact" | "/fr/contact" | default -> fr |
"/fr" | "/" | fr -> default |
"/fr/contact" | "/contact" | fr -> default |
"/es/contact" | "/fr-CA/contact" | es -> fr-CA |
"/es" | "/fr-CA" | es -> fr-CA |
Usage example:
translate_url
Just like the translate_path
helper, but it prepends the baseUrl
if set in the config.
locale_path
To avoid hard coding the current_locale
into paths
, input only the partial path that comes after the locale code
part into this helper and it will handle the rest for you.
$partial_path | current_locale | href |
---|---|---|
"/" | DEFAULT | "/" |
"/" | "fr" | "/fr" |
"/contact" | DEFAULT | "/contact" |
"/contact" | "fr" | "/fr/contact" |
locale_url
Just like the locale_path
helper, but it prepends the baseUrl
if set in the config.
Live test
Wanna see a project that is up and running with this library? checkout this repo
TODO
- Test behavior with non A-Z languages.
- Add a router with named routes
- Allow custom route patterns (for example set /blog/{locale}/)
Contributing
Any help is very welcomed, feel free to fork and PR :)