🌍 RTK - Translate (React Kit Translate)

RTK - Translate é uma biblioteca criada para simplificar a tradução de seu site, portfólio, software e muito mais. Projetada para ser simples, intuitiva e prática. Integre-a facilmente em seus projetos e suporte quantos idiomas desejar.

📦 Instalação

Usando npm:

npm install rtk-translate

Usando yarn:

yarn add rtk-translate

🚀 Como começar

1. Configuração Inicial

Envolva o componente principal da sua aplicação com o TranslationProvider e passe as propriedades necessárias:

import { TranslationProvider } from 'rtk-translate';

function App() {
  return (
    <TranslationProvider 
        storageKey='sua-chave-no-storage' // Chave usada para salvar o idioma selecionado no storage.
        languages={...} // Forneça seus idiomas e traduções aqui. Veja o exemplo abaixo.
        defaultLanguage="seu-idioma-default" // Idioma padrão da aplicação.
        availableLanguages={['pt', 'en', ...]} // Idiomas que você disponibilizou nas traduções. Exemplo abaixo.
    >
      <MyComponent />
    </TranslationProvider>
  );
}

📝 Propriedades do `TranslationProvider`

Veja aqui

Propriedade	Tipo	Descrição
`storageKey`	`string`	Usado para salvar o idioma atual no localStorage, ela é opcional, caso não seja passada será salvo com a chave `rtk::language`.
`languages`	`object`	Objeto contendo os idiomas, chaves de identificação e as traduções desejadas.
`defaultLanguage`	`string`	Define um idioma padrão para o seu projeto, caso não seja passado será usado o valor default `pt`.
`availableLanguages`	`string[]`	Array contendo todos os idiomas disponíveis no seu array `languages`.

Exemplo de `languages`:

Veja aqui

const languages = {
  pt: {
    heading: 'Título 1',
    subheading: 'Subtítulo A',
    buttonLabel: 'Clique Aqui',
    contactUs: 'Fale Conosco'
  },
  en: {
    heading: 'Title 1',
    subheading: 'Subheading A',
    buttonLabel: 'Click Here',
    contactUs: 'Contact Us'
  },
  fr: {
    heading: 'Titre 1',
    subheading: 'Sous-titre A',
    buttonLabel: 'Cliquez ici',
    contactUs: 'Contactez-nous'
  },
  es: {
    heading: 'Título 1',
    subheading: 'Subtítulo A',
    buttonLabel: 'Haz clic aquí',
    contactUs: 'Contáctenos'
  }
  // ...
}

Exemplo de `availableLanguages`:

Veja aqui

const availableLanguages = ['pt', 'en', 'fr', 'es'];

2. Uso dentro dos componentes

Exemplo de uso com select:

import { useTranslation } from 'rtk-translate';

function SellectLang() {
  const { translateText, setCurrentLanguage, currentLanguage } = useTranslation();

  const handleLanguageChange = (event) => {
    setCurrentLanguage(event.target.value);
  };

  return (
  <div>
      // Exemplo de uso com um select padrão para mudar o idioma
      <select onChange={handleLanguageChange} defaultValue={currentLanguage}>
        <option value="en">English</option>
        <option value="pt">Português</option>
        <option value="fr">Français</option>
        <option value="es">Español</option>
      </select>
      <div>
        <h1>{translateText('heading')}</h1> // traduz o texto com a chave 'heading'
        <h2>{translateText('subheading')}</h2> // traduz o texto com a chave 'subheading'
        <button>{translateText('buttonLabel')}</button> // traduz o texto com a chave 'buttonLabel'
        <a href="/contact">{translateText('contactUs')}</a> // traduz o texto com a chave 'contactUs'
      </div>
    </div>
  );
}

Exemplo de uso com botões:

⚠️ o onClick precisa ter uma callback, conforme o código abaixo!

import { useTranslation } from 'rtk-translate';

function ButtonsLang() {
  const { setCurrentLanguage } = useTranslation();

  const handleLanguageChange = (lang) =>  setCurrentLanguage(lang);

  return (
    <section>
      <ul>
        <li><button onClick={() => handleLanguageChange('pt')}>🇧🇷 PT-BR</button></li>
        <li><button onClick={() => handleLanguageChange('en')}>🇺🇸 EN</button></li>
      </ul>
    </section>
  )
}

3. Componente `LanguageSelect`

O componente LanguageSelect é um seletor de idiomas desenvolvido para facilitar a experiência de internacionalização no seu site. Ele foi projetado pensando na usabilidade e eficiência, por isso apresenta as seguintes características:

Idioma e Bandeira: Cada opção no dropdown é representada pelo nome do idioma e uma bandeira correspondente, tornando visualmente intuitivo para os usuários. Se preferir uma abordagem mais minimalista, é possível ocultar o nome e exibir apenas a bandeira.
Pesquisa Rápida: Sabendo que alguns sites podem suportar uma extensa lista de idiomas, um campo de pesquisa foi incorporado ao dropdown. Ao clicar no seletor, um input é renderizado no topo do menu dropdown, permitindo que os usuários digitem e filtrem rapidamente para encontrar o idioma desejado.

⚠️ O nome e o input funcionam em conjunto, ou seja, se o nome do idioma estiver oculto, o input de pesquisa também será oculto. Para exibir o input de pesquisa, o nome do idioma deve estar visível.

Utilize o LanguageSelect para oferecer uma navegação fluída e uma experiência de usuário enriquecedora, independente do número de idiomas que seu site suporta.

Exemplo de uso do componente `LanguageSelect`:

import { LanguageSelect, useTranslation } from 'rtk-translate';

// import o arquivo css 
import 'rtk-translate/dist/index.css'

function MyComponent() {
  const { translateText, setCurrentLanguage, currentLanguage, validLanguages } = useTranslation();

  return (
    <div>
      <LanguageSelect
        selected={currentLanguage}
        onChange={setCurrentLanguage}
        availableLanguages={validLanguages}
        // isNameVisible={true}
        // showSearchInput={true}
      />
      <div>
        <h1>{translateText('heading')}</h1>
        <h2>{translateText('subheading')}</h2>
        <button>{translateText('buttonLabel')}</button>
        <a href="/contact">{translateText('contactUs')}</a>
      </div>
    </div>
  );
}

📝 Propriedades do componente `LanguageSelect`

Veja aqui

Propriedade	Tipo	Descrição
`selected`	`string`	Idioma atual do site, pode ser obtido através da propriedade `currentLanguage` do `useTranslation()`.
`onChange`	`function`	Função que muda o idioma atual do site. Pode ser obtida através da propriedade `setCurrentLanguage` do `useTranslation()`.
`availableLanguages`	`string[]`	Array que a `rtk-translate` já validou com base nos seus idiomas fornecidos ao `TranslationProvider`. É disponibilizado através da propriedade `validLanguages` do `useTranslation()`.
`isNameVisible`	`boolean`	Booleano que define se o nome do idioma será renderizado junto com a bandeira, o valor default é `true`.
`showSearchInput`	`boolean`	Booleano que define se o campo de pesquisa será renderizado no dropdown, o valor default é `true`.

📝 Propriedades do `useTranslation()`

Veja aqui

Propriedade	Tipo	Descrição
`translateText`	`function`	Função que retorna a tradução correspondente à chave fornecida. Recebe a chave do texto que deseja traduzir.
`setCurrentLanguage`	`function`	Função que define o idioma atual do site. Recebe o novo idioma desejado como parâmetro.
`currentLanguage`	`string`	Representa o idioma atual em uso no site.
`validLanguages`	`string[]`	Array de idiomas validados pela `rtk-translate`, com base nos idiomas fornecidos ao `TranslationProvider`.

🎨 Classes `CSS` para `Customização` do componente `LanguageSelect`

Aqui estão as classes CSS que você pode sobrescrever para personalizar a aparência do componente LanguageSelect:

Veja aqui

Classe	Descrição	Sobrescrição Sugerida
`.rtk-language-selector`	Estilização geral do seletor de idioma.	`.rtk-language-selector { ... !important; }`
`.rtk-current-language`	Estilo do idioma atual exibido.	`.rtk-current-language { ... !important; }`
`.rtk-current-language > img`	Estilo da imagem/bandeira do idioma atual.	`.rtk-current-language > img { ... !important; }`
`.rtk-languages-dropdown`	Estilo do menu dropdown que lista os idiomas.	`.rtk-languages-dropdown { ... !important; }`
`.rtk-languages-dropdown .rtk-language-option > img`	Estilo da imagem/bandeira nos itens do dropdown.	`.rtk-languages-dropdown .rtk-language-option > img { ... !important; }`
`.rtk-language-option, .rtk-language-no-results`	Estilo dos itens individuais no dropdown.	`.rtk-language-option { ... !important; }`
`.rtk-language-option:last-child`	Estilo para o último item no dropdown.	`.rtk-language-option:last-child { ... !important; }`
`.rtk-language-option:hover`	Estilo hover dos itens no dropdown.	`.rtk-language-option:hover { ... !important; }`
`.rtk-language-input-search`	Estilo do campo de busca no dropdown.	`.rtk-language-input-search { ... !important; }`

Como contribuir

Para contribuir com o projeto, leia o arquivo CONTRIBUTING.md

Mais infos

Rtk Translate - repositório no GitHub.

🔗 Veja uma demonstração ao vivo aqui.

⭐️ Este README foi gerado a partir do Gerador de README drag in drop. Experimente aqui: Code Mark

rtk-translate

🌍 RTK - Translate (React Kit Translate)

📦 Instalação

🚀 Como começar

1. Configuração Inicial

📝 Propriedades do `TranslationProvider`

Exemplo de `languages`:

Exemplo de `availableLanguages`:

2. Uso dentro dos componentes

Exemplo de uso com select:

Exemplo de uso com botões:

3. Componente `LanguageSelect`

Exemplo de uso do componente `LanguageSelect`:

📝 Propriedades do componente `LanguageSelect`

📝 Propriedades do `useTranslation()`

🎨 Classes `CSS` para `Customização` do componente `LanguageSelect`

Como contribuir

Mais infos

Dúvidas, sugestões e melhorias

Referências

Licença

Agradecimentos

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

rtk-translate

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads