gsferro/translation-solution-easy

A complete solution for simple and efficient i18n for Laravel

Maintainers

Details

github.com/GuilhermeFerro/laravel-translation-solution-easy

Source

Issues

Installs: 176

Dependents: 0

Suggesters: 0

Security: 0

Stars: 5

Watchers: 2

Forks: 0

v1.3.0 2021-12-27 23:46 UTC

Requires

MIT d3d47771879903f356caf1bb996308658546b145

  • Guilherme Ferro <gsferroti.woop@gmail.com>

This package is auto-updated.

Last update: 2024-10-28 07:14:58 UTC

README

Uma solução robusta e fácil para i18n que contempla as 3 etapas básicas:

  1. Tradução de termos (strings) fixos (views e controllers)

    1. Crie o arquivo resources/lang/pt-br.json e coloque os termos fixos, que são usados em todos os lugares, como:

      • titulos das paginas
      • breadcumb
      • menu
      • label ou _coluna de tabela
      • frases / textos
      1. Escreva-os como forem ser usados em pt-br:
        • ex:
        {
   "Nome": "Nome",
   "Email": "Email",
   "Nome Social": "Nome Social",
   "Termos de compromisso de uso": "Termos de compromisso de uso"
}
      2. Para executar, utilize normalmente o método padrão do laravel:
        • ex:
        echo __("Nome Social"); 
# ou
{{ __("Termos de compromisso de uso") }}
    • Crie os arquivos em resources/lang/pt-br/<arquivo>.php somente quando o valor for sofrer alteração conforme utilização, faça parte de um componente ou for explícito alguma tradução em especial.
      • ex:
        # crud-pessoa.php
  <?php
  
  return [
      "index" => ":attribute recuperados(as) com sucesso",
  ];
  
  // uso
  echo __("crud-pessoa.index", ["attribute" => "Pessoa"]);
    • Observações relevantes:

      1. Acaba sendo inicialmente trabalhoso encapsular todos os textos/termos e incrementar o arquivo json quando o projeto já está em curso

      2. Ficará muito mais fácil quando o projeto nasce com essa filosofia

      3. Reforce o princípio dentro do time de que em qualquer alteração, encapsular os textos/termos

      4. Não utilize espaço no nome do index dentro dos arquivos php, use o separador _ ou -

      5. ATENÇÃO: não utilize array bidimensional, a exceção é o validation.php

    1. Para traduzir os arquivos, veja a sessão Tradução dos arquivos de langs usando command como é feito para o banco de dados 
      php artisan gsferro:translate-files

  2. Gerenciamento do Langs

    1. Veja a sessão: Configurações de uso item 1, 2 e 5
    2. O locale ficará como prefixo na url, porém a langs padrão (pt-br), não é exibido
    3. A gerência é feita de forma automática pelo pacote, você só precisa incluir na view @translationsolutioneasyFlags() para o usuário fazer a troca
    4. O pacote também verifica o browser do usuário para ajudar a setar o locate
    5. Ao fazer chamadas para alguma api que venha a ser feita, colocar no header do http "accept-language" => "pt-BR,pt;q=0.8",
    6. O pacote olha primeiro para a base de dados e depois para o arquivo seguindo o padrão Iterator, nas próximas versões inverteremos, mas nada que irá modificar o seu uso.

  3. Tradução do banco de dados

    1. Caso queira utilizar o Sqlite veja a sessão Use SQLite, no link é visto como configurar de forma simples com alguns passos rodando: 
      php artisan gsferro:configure-sqlite
    2. Na Sessão Tradução do Banco de Dados, é explicado como configurar o pacote para traduzir um ou múltiplas tabelas e colunas no arquivo config/translationsolutioneasy: 
      php artisan gsferro:translate-tables
  • TODO

    1. Traduzir automaticamente informações digitadas pelos usuários?

      • se sim, usar Observer ou listener?

    2. Ao traduzir automaticamente, ter a opção de uma verificação interna (PF / time) e/ou dos usuários do sistema poderem sugerir melhores traduções.

Dependências:

  1. https://github.com/spatie/laravel-translation-loader/tree/2.6.3
  2. https://github.com/mcamara/laravel-localization/

Versões

Instalação

composer require gsferro/translation-solution-easy

php artisan vendor:publish --provider="Mcamara\LaravelLocalization\LaravelLocalizationServiceProvider"
php artisan vendor:publish --provider="Gsferro\TranslationSolutionEasy\Providers\TranslationSolutionEasyServiceProvider" --force
  • Faz mergeConfigFrom no ServiceProvider colocando o locale de app.php como pt-br
  • TODO trocar configuração via command

Configurações de uso

  1. No arquivo base de html deve ser colocado:

    <html lang="{{ strtolower(str_replace('_', '-', app()->getLocale())) }}">

  2. Para o fácil encapsulamento e visando os testes automatizados:

    • Crie o arquivo routes/withLacale.php
        <?php
    
    if (app()->environment("testing")) {
        require "web.php";
    } else {
        Route::prefix(LaravelLocalization::setLocale())
            ->middleware(["localeSessionRedirect", "localizationRedirect", "localeViewPath"])
            ->group(function () {
                require "web.php";
            });
    }
    • Altere RouteServiceProvider@mapWebRoutes
        Route::middleware("web")
         ->namespace($this->namespace)
         ->group(base_path("routes/withLacale.php"));

  3. Caso não opte por Use SQLite, execute no terminal:

    php artisan migrate --path=database/migrations/translation
    • Caso use uma outra conexão: 
      php artisan migrate --path=database/migrations/translation --database=<outra-conexão>

  4. Acesse config/laravellocalization e sete quais linguas a sua aplicação irá dar suporte

    • default:
      • pt-br
      • en

  5. Inclua a seleção para troca de idiomas

    • @translationsolutioneasyFlags()
    • Ele precisa estar encapsulado pela tag <ul>
    • Talvez seja necessário ajustar o public/vendor/gsferro/translationsolutioneasy/css/flags.css dependendo de onde for colocado

Use SQLite

  1. Command para criar database 
    php artisan gsferro:configure-sqlite {--database= : Database name}
  • Faz mergeConfigFrom no ServiceProvider mesclando a nova config em config/database e config/translationsolutioneasy
  1. Migrate 
    php artisan gsferro:configure-sqlite-migrate
  • Caso queria deixar de usar o SQLite para usar outro SGBD, excluir arquivos de vendor/gsferro/translation-solution-easy/config/sqlite
  • TODO remover configuração via command

Tradução dos Arquivos

  1. Execute o comando via artisan, passe os paramentros caso queira rodar somente em um único arquivo ou lang 
    php artisan gsferro:translate-files [--file= : File name] [--lang= : Language] [--force :  : default false, execute translate if no exists]

Tradução do Banco de Dados

  1. Coloque em config/translationsolutioneasy.translate-tables as tabelas com o(s) campo(s) que deseja traduzir:

    • ex:
        "translate-tables" => [
        "paises" => "nome", 
        // ou
        "servicos" => [
            "nome",
            "descricao",
            "observacoes",
        ]
    ],
    • Obs: Coloque somente as colunas que fazem sentido serem traduzidas. Colunas contendo datas e numero não fazem.

  2. Nas Models:

    1. Coloque a interface TranslationColumnsInterface
    2. Coloque a Trait TranslationColumnsTrait
    3. Caso não tenha configurado o item 1 (inline), sete o atributo public $translationColumns = ["<name-column1>", ...]

  3. Execute o comando via artisan, passe os paramentos caso queira rodar somente numa única tabela/coluna (inline)

    php artisan gsferro:translate-tables [--table= : Table name] [--column= : Collumn name]  [--lang= : Language] [--force :  : default false, execute translate if no exists]
  • TODO
    • Ter a opção de passar a model e pegar as informações direto dela, assim é viável fazer traduções em multiplas conexões de banco de dados.

Informações Adicionais / Importantes

Credits

License

Laravel Localization is an open-sourced laravel package licensed under the MIT license