|
| 1 | +# Laravel Localized Routes |
| 2 | + |
| 3 | +This package is in development. Feedback is much appreciated! |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- [Automatically register](#register-routes) a route for each locale you wish to support. |
| 8 | +- [Generate localized route URL's](#generate-route-urls) in the simplest way using the `route()` helper. |
| 9 | +- [Redirect to localized routes](#redirect-to-routes) using the `redirect()->route()` helper. |
| 10 | +- Allow routes to be [cached](#cache-routes). |
| 11 | +- Let you work with routes without thinking too much about locales. |
| 12 | +- Optionally [translate each segment](#translate-routes) in your URI's. |
| 13 | + |
| 14 | +## Install |
| 15 | + |
| 16 | +``` |
| 17 | +composer require codezero/laravel-localized-routes |
| 18 | +``` |
| 19 | + |
| 20 | +> Laravel >= 5.5 will automatically register the ServiceProvider. |
| 21 | +
|
| 22 | +## Configure Supported Locales |
| 23 | + |
| 24 | +Add a `locales` key to your `config/app.php` file. |
| 25 | + |
| 26 | +```php |
| 27 | +'locales' => [ |
| 28 | + 'en', |
| 29 | + 'nl', |
| 30 | + //... |
| 31 | +], |
| 32 | +``` |
| 33 | + |
| 34 | +## Register Routes |
| 35 | + |
| 36 | +Example: |
| 37 | + |
| 38 | +```php |
| 39 | +// Not localized |
| 40 | +Route::get('home', HomeController::class.'@index') |
| 41 | + ->name('home'); |
| 42 | + |
| 43 | +// Localized |
| 44 | +Route::localized(function () { |
| 45 | + |
| 46 | + Route::get('about', AboutController::class.'@index') |
| 47 | + ->name('about'); |
| 48 | + |
| 49 | + Route::name('admin.')->group(function () { |
| 50 | + Route::get('admin/reports', ReportsController::class.'@index') |
| 51 | + ->name('reports.index'); |
| 52 | + }); |
| 53 | + |
| 54 | +}); |
| 55 | +``` |
| 56 | + |
| 57 | +In the above example there are 5 routes being registered. The routes defined in the `Route::localized` closure are automatically registered for each configured locale. This will prepend the locale to the route's URI and name. |
| 58 | + |
| 59 | +| URI | Name | |
| 60 | +| ----------------- | ---------------------- | |
| 61 | +| /home | home | |
| 62 | +| /en/about | en.about | |
| 63 | +| /nl/about | nl.about | |
| 64 | +| /en/admin/reports | en.admin.reports.index | |
| 65 | +| /nl/admin/reports | nl.admin.reports.index | |
| 66 | + |
| 67 | +## Generate Route URL's |
| 68 | + |
| 69 | +You can get the URL of your named routes as usual, using the `route()` helper. |
| 70 | + |
| 71 | +Normally you would have to include the locale whenever you want to generate a URL: |
| 72 | + |
| 73 | +```php |
| 74 | +$url = route(app()->getLocale().'.admin.reports.index'); |
| 75 | +``` |
| 76 | + |
| 77 | +Because that's rather ugly, this package overwrites the `route()` function and the underlying `UrlGenerator` class with an additional, optional `$locale` argument and takes care of the locale prefix for you. If you don't specify a locale, either a normal, non-localized route or a route in the current locale is returned. |
| 78 | + |
| 79 | +```php |
| 80 | +route($name, $parameters = [], $absolute = true, $locale = null) |
| 81 | +``` |
| 82 | + |
| 83 | +A few examples: |
| 84 | + |
| 85 | +```php |
| 86 | +app()->setLocale('en'); |
| 87 | +app()->getLocale(); // 'en' |
| 88 | + |
| 89 | +$url = route('home'); // /home (normal routes have priority) |
| 90 | +$url = route('about'); // /en/about (current locale) |
| 91 | + |
| 92 | +// Get specific locales... |
| 93 | +// This is most useful if you want to generate a URL to switch language. |
| 94 | +$url = route('about', [], true, 'en'); // /en/about |
| 95 | +$url = route('about', [], true, 'nl'); // /nl/about |
| 96 | + |
| 97 | +// You could also do this, but it kinda defeats the purpose... |
| 98 | +$url = route('en.about'); // /en/about |
| 99 | +$url = route('en.about', [], true, 'nl'); // /nl/about |
| 100 | +``` |
| 101 | + |
| 102 | +> **Note:** in a most practical scenario you would register a route either localized **or** non-localized, but not both. If you do, you will always need to specify a locale to get the URL, because non-localized routes always have priority when using the `route()` function. |
| 103 | +
|
| 104 | +## Redirect to Routes |
| 105 | + |
| 106 | +Laravel's `Redirector` uses the same `UrlGenerator` as the `route()` function behind the scenes. Because we are overriding this class, you can easily redirect to your routes. |
| 107 | + |
| 108 | +```php |
| 109 | +return redirect()->route('home'); // redirects to /home |
| 110 | +return redirect()->route('about'); // redirects to /en/about (current locale) |
| 111 | +``` |
| 112 | + |
| 113 | +You can't redirect to URL's in a specific locale this way, but if you need to, you can of course just use the `route()` function. |
| 114 | + |
| 115 | +```php |
| 116 | +return redirect(route('about', [], true, 'nl')); // redirects to /nl/about |
| 117 | +``` |
| 118 | + |
| 119 | +## Translate Routes |
| 120 | + |
| 121 | +If you want to translate the segments of your URI's, create a `routes.php` language file for each locale you [configured](#configure-supported-locales): |
| 122 | + |
| 123 | +``` |
| 124 | +resources/ |
| 125 | + |-lang/ |
| 126 | + |-en/ |
| 127 | + | |-routes.php |
| 128 | + |-nl/ |
| 129 | + |-routes.php |
| 130 | +``` |
| 131 | + |
| 132 | +In these files, add a translation for each segment. |
| 133 | + |
| 134 | +```php |
| 135 | +// lang/nl/routes.php |
| 136 | +return [ |
| 137 | + 'about' => 'over', |
| 138 | + 'us' => 'ons', |
| 139 | +]; |
| 140 | +``` |
| 141 | + |
| 142 | +Now you can use our `Lang::uri()` macro during route registration: |
| 143 | + |
| 144 | +```php |
| 145 | +Route::localized(function () { |
| 146 | + |
| 147 | + Route::get(Lang::uri('about/us'), AboutController::class.'@index') |
| 148 | + ->name('about.us'); |
| 149 | + |
| 150 | +}); |
| 151 | +``` |
| 152 | + |
| 153 | +The above will generate: |
| 154 | + |
| 155 | +- /en/about/us |
| 156 | +- /nl/over/ons |
| 157 | + |
| 158 | +> If a translation is not found, the original segment is used. |
| 159 | +
|
| 160 | +## Route Placeholders |
| 161 | + |
| 162 | +Placeholders are not translated via language files. These are values you would provide via the `route()` function. The `Lang::uri()` macro will skip any placeholder segment. |
| 163 | + |
| 164 | +If you have a model that uses a route key that is translated in the current locale, then you can still simply pass the model to the `route()` function to get translated URL's. |
| 165 | + |
| 166 | +An example... |
| 167 | + |
| 168 | +#### Given we have a model like this: |
| 169 | + |
| 170 | +```php |
| 171 | +class Post extends \Illuminate\Database\Eloquent\Model |
| 172 | +{ |
| 173 | + public function getRouteKey() |
| 174 | + { |
| 175 | + $slugs = [ |
| 176 | + 'en' => 'en-slug', |
| 177 | + 'nl' => 'nl-slug', |
| 178 | + ]; |
| 179 | + |
| 180 | + return $slugs[app()->getLocale()]; |
| 181 | + } |
| 182 | +} |
| 183 | +``` |
| 184 | + |
| 185 | +> **TIP:** checkout [spatie/laravel-translatable](https://github.com/spatie/laravel-translatable) for translatable models. |
| 186 | +
|
| 187 | +#### If we have a localized route like this: |
| 188 | + |
| 189 | +```php |
| 190 | +Route::localized(function () { |
| 191 | + |
| 192 | + Route::get('posts/{post}', PostsController::class.'@show') |
| 193 | + ->name('posts.show'); |
| 194 | + |
| 195 | +}); |
| 196 | +``` |
| 197 | + |
| 198 | +#### We can now get the URL with the appropriate slug: |
| 199 | + |
| 200 | +```php |
| 201 | +app()->setLocale('en'); |
| 202 | +app()->getLocale(); // 'en' |
| 203 | + |
| 204 | +$post = new Post; |
| 205 | + |
| 206 | +$url = route('posts.show', $post); // /en/posts/en-slug |
| 207 | +$url = route('posts.show', $post, true, 'nl'); // /nl/posts/nl-slug |
| 208 | +``` |
| 209 | + |
| 210 | +## Cache Routes |
| 211 | + |
| 212 | +In production you can safely cache your routes per usual. |
| 213 | + |
| 214 | +```php |
| 215 | +php artisan route:cache |
| 216 | +``` |
| 217 | + |
| 218 | +## Testing |
| 219 | + |
| 220 | +``` |
| 221 | +composer test |
| 222 | +``` |
| 223 | + |
| 224 | +## Security |
| 225 | + |
| 226 | +If you discover any security related issues, please [e-mail me](mailto:ivan@codezero.be) instead of using the issue tracker. |
| 227 | + |
| 228 | +## Changelog |
| 229 | + |
| 230 | +See a list of important changes in the [changelog](CHANGELOG.md). |
| 231 | + |
| 232 | +## License |
| 233 | + |
| 234 | +The MIT License (MIT). Please see [License File](LICENSE.md) for more information. |
0 commit comments