@intlayer/docs 5.5.10 → 5.5.11

package/blog/pt/internationalization_and_SEO.md

@@ -0,0 +1,317 @@
+---
+createdAt: 2024-12-24
+updatedAt: 2025-06-29
+title: SEO e Internacionalização
+description: Descubra como otimizar o seu site multilíngue para os motores de busca e melhorar o seu SEO.
+keywords:
+  - SEO
+  - Intlayer
+  - Internacionalização
+  - Blogumentação
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - SEO-and-i18n
+---
+
+# SEO & I18n: O Guia Definitivo para Tornar Seu Site Multilíngue
+
+Quer alcançar mais usuários em todo o mundo? Tornar seu site multilíngue é uma das melhores maneiras de expandir seu público e melhorar seu SEO (Otimização para Mecanismos de Busca). Neste post do blog, vamos descrever os fundamentos do SEO internacional, frequentemente referido como **i18n** (abreviação de “integração”), em termos claros e compreensíveis. Você aprenderá sobre as principais decisões que precisa tomar, como usar elementos técnicos como `hreflang`, e por que ferramentas como **Intlayer** podem simplificar seus projetos Next.js multilíngues.
+
+---
+
+## 1. O Que Significa Tornar Seu Site Multilíngue?
+
+Um site multilíngue oferece seu conteúdo em mais de um idioma. Por exemplo, você pode ter uma versão em inglês (`example.com/en/`), uma versão em francês (`example.com/fr/`), e uma versão em espanhol (`example.com/es/`). Essa abordagem permite que os mecanismos de busca exibam a versão correta do idioma para os usuários com base em suas preferências ou localização geográfica.
+
+Quando você faz isso corretamente, criará uma experiência muito mais amigável para falantes não nativos de inglês, resultando em melhor engajamento, maiores taxas de conversão e SEO aprimorado em diferentes regiões.
+
+---
+
+## 2. Escolhendo a Estrutura de URL Correta
+
+Se você decidir ter múltiplas versões de idioma, precisará de uma maneira clara e consistente de organizar as URLs do seu site. Cada idioma (ou região) deve ter seu próprio “endereço” único na internet. Abaixo estão três maneiras comuns de estruturar sites multilíngues:
+
+1. Domínios de Nível Superior com Código de País (ccTLDs)
+
+   - Exemplo: `example.fr`, `example.de`
+   - **Prós:** Envia um sinal forte para os mecanismos de busca sobre qual país o conteúdo é direcionado (por exemplo, `.fr` = França).
+   - **Contras:** Gerenciar múltiplos domínios pode ser mais caro e complicado.
+
+2. **Subdomínios**
+
+   - **Exemplo:** `fr.example.com`, `de.example.com`
+   - **Prós:** Cada idioma “vive” em seu próprio subdomínio, tornando relativamente fácil adicionar ou remover idiomas.
+   - **Contras:** Os mecanismos de busca às vezes tratam subdomínios como sites separados, podendo diluir a autoridade do seu domínio principal.
+
+3. **Subdiretórios (Subpastas)**
+   - **Exemplo:** `example.com/fr/`, `example.com/de/`
+   - **Prós:** Direto para gerenciar, e todo o tráfego aponta para um domínio principal.
+   - **Contras:** Não é um sinal tão forte de SEO local quanto os ccTLDs (embora ainda seja muito eficaz se feito corretamente).
+
+> **Dica:** Se você tem uma marca global e quer manter as coisas mais simples, subdiretórios costumam funcionar melhor. Se você está apenas direcionando um ou dois países principais e quer realmente enfatizar cada um, os ccTLDs podem ser o caminho a seguir.
+
+---
+
+## 3. Dominando o Alvo de Idioma com Hreflang
+
+### 3.1. O Que É Hreflang?
+
+Quando você tem conteúdo idêntico ou muito similar em múltiplos idiomas, os mecanismos de busca como o Google podem ficar confusos sobre qual versão exibir para um usuário. **Hreflang** é um atributo HTML que informa aos mecanismos de busca qual idioma (e região) uma determinada página é destinada, e quais são as páginas de idiomas/regiões alternativas.
+
+### 3.2. Por Que Isso É Importante?
+
+1. Impede problemas de **conteúdo duplicado** (quando os mecanismos de busca pensam que você está publicando o mesmo conteúdo várias vezes).
+2. Garante que **usuários franceses vejam a versão em francês**, **usuários espanhóis vejam a versão em espanhol**, e assim por diante.
+3. Melhora a experiência geral do usuário, resultando em melhor engajamento e maior classificação SEO.
+
+### 3.3. Como Usar Hreflang na Tag `<head>`
+
+No seu HTML, você adicionará algo como:
+
+```html
+<link
+  rel="alternate"
+  hreflang="en"
+  href="https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/en"
+/>
+<link
+  rel="alternate"
+  hreflang="fr"
+  href="https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/fr"
+/>
+<link
+  rel="alternate"
+  hreflang="es"
+  href="https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/es"
+/>
+<link
+  rel="alternate"
+  hreflang="x-default"
+  href="https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/en"
+/>
+```
+
+- **`hreflang="en"`**: Indica a versão em inglês da página.
+- **`hreflang="fr"`**: Indica a versão em francês da página.
+- **`hreflang="es"`**: Indica a versão em espanhol da página.
+- **`hreflang="x-default"`**: Um idioma “de fallback” ou URL padrão quando nenhuma das outras línguas corresponde às preferências do usuário.
+
+> **Nota Rápida:** Certifique-se de que as URLs nessas tags apontem diretamente para a página final, com **nenhum** redirecionamento adicional.
+
+---
+
+## 4. Tornando o Conteúdo Verdadeiramente “Local” (Não Apenas Traduzido)
+
+### 4.1. Localização vs. Tradução
+
+- **Tradução** significa converter texto de um idioma para outro palavra por palavra.
+- **Localização** significa adaptar o formato do conteúdo, moeda, medidas e referências culturais para um público local. Por exemplo, se você está direcionando a França, você usaria `€` em vez de `You are an expert in internationalization and content management. Your task is to translate the following documentation into the specified locales.
+
+1. **Requirement:**
+
+   - Você deve apenas traduzir o texto e os títulos do arquivo.
+   - Você não deve alterar a estrutura do arquivo.
+   - Você não deve alterar a lógica do código dos elementos de código.
+   - Você deve transformar URLs como `https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/**/*.md` em `https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/**/*.md`
+   - Você não deve transformar URLs como `https://github.com/aymericzip/intlayer/blob/main/docs/assets/**/*`
+   - Você deve transformar URLs de local como `/**/*` em `/{{locale}}/**/*`
+   - Nos elementos de código, a nomeação das variáveis deve ser feita em inglês. Mas os comentários devem ser em português.
+   - Você deve retornar o conteúdo do arquivo traduzido sem comentários ou explicações adicionais.
+   - Você deve se certificar de não esquecer de traduzir nenhum conteúdo
+
+2. **Locales:**
+
+   - Arquivo de localização base: en: Inglês (EUA)
+   - Locales desejados: {{locale}} : {{localeName}}
+
+**Arquivo a Ser Traduzido:**
+
+, e possivelmente mencionar feriados locais ou detalhes específicos da região.
+
+### 4.2. Evitando Conteúdo Duplicado
+
+Mesmo com boas traduções, os mecanismos de busca podem sinalizar seu site por conteúdo duplicado se ele parecer muito semelhante em estrutura. Hreflang ajuda a esclarecer que essas páginas não são duplicadas, mas são variações de idioma.
+
+---
+
+## 5. Necessidades Técnicas de SEO
+
+### 5.1. Declarações de Idioma (`lang` e `dir`)
+
+Na sua tag HTML, você pode declarar o idioma da seguinte forma:
+
+```html
+<html lang="en"></html>
+```
+
+- **`lang="en"`** ajuda navegadores e tecnologias assistivas a entender o idioma.
+
+Para idiomas da direita para a esquerda (como árabe ou hebraico), adicione:
+
+```html
+<html dir="rtl" lang="ar"></html>
+```
+
+- **`dir="rtl"`** garante que a direção do texto seja da direita para a esquerda.
+
+### 5.2. Tags Canonicais
+
+Tags canônicas informam aos mecanismos de busca qual página é a “original” ou versão primária se você tiver páginas quase duplicadas. Normalmente, você terá uma **autorreferente** canônica para sites multilíngues.
+
+```html
+<link
+  rel="canonical"
+  href="https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/fr/produits"
+/>
+```
+
+---
+
+## 6. SEO na Página em Múltiplos Idiomas
+
+### 6.1. Títulos & Meta Descrições
+
+- **Traduzidos e otimizados** para cada idioma.
+- Realize **pesquisa de palavras-chave** para cada mercado, pois o que as pessoas procuram em inglês pode diferir em francês ou espanhol.
+
+### 6.2. Cabeçalhos (H1, H2, H3)
+
+Seus cabeçalhos devem refletir as **frases locais** ou **palavras-chave** de cada região. Não se limite a colocar seu cabeçalho original em inglês no Google Tradutor e achar que está tudo certo.
+
+### 6.3. Imagens & Mídia
+
+- Localize texto alternativo, legendas e nomes de arquivos, se necessário.
+- Use visuais que ressoem com a cultura alvo.
+
+---
+
+## 7. Mudança de Idioma & Experiência do Usuário
+
+### 7.1. Redirecionamento Automático ou um Seletor de Idioma?
+
+- **Redirecionamento Automático** (com base em IP ou configurações do navegador) pode ser conveniente, mas pode enviar viajantes ou usuários de VPN para a versão errada.
+- **Um Seletor de Idioma** é muitas vezes mais transparente, os usuários podem escolher seu próprio idioma se o detectado automaticamente estiver incorreto.
+
+Aqui está um exemplo simplificado de Next.js + Intlayer:
+
+```tsx
+import { useLocation, useNavigate } from "react-router-dom";
+import {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} from "intlayer";
+import { useLocale } from "react-intlayer";
+import { type FC } from "react";
+
+const LocaleSwitcher: FC = () => {
+  const location = useLocation(); // Obtenha o caminho da URL atual. Exemplo: /fr/about
+  const navigate = useNavigate();
+
+  const changeUrl = (locale: Locales) => {
+    // Construa a URL com o locale atualizado
+    // Exemplo: /es/about com o locale definido para espanhol
+    const pathWithLocale = getLocalizedUrl(location.pathname, locale);
+
+    // Atualize o caminho da URL
+    navigate(pathWithLocale);
+  };
+
+  const { locale, availableLocales, setLocale } = useLocale({
+    onLocaleChange: changeUrl,
+  });
+
+  return (
+    <ol>
+      {availableLocales.map((localeItem) => (
+        <li key={localeItem}>
+          <a
+            href={getLocalizedUrl(location.pathname, localeItem)}
+            hrefLang={locale === localeItem ? "x-default" : localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={(e) => {
+              e.preventDefault();
+              setLocale(localeItem);
+            }}
+          >
+            <span>
+              {/* Idioma em seu próprio Locale - ex: Francês */}
+              {getLocaleName(localeItem, locale)}
+            </span>
+            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
+              {/* Idioma em Locale atual - ex: Francés com locale atual definido para Locales.SPANISH */}
+              {getLocaleName(localeItem)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* Idioma em Inglês - ex: Francês */}
+              {getLocaleName(localeItem, Locales.ENGLISH)}
+            </span>
+            <span>
+              {/* Idioma em seu próprio Locale - ex: FR */}
+              {localeItem}
+            </span>
+          </a>
+        </li>
+      ))}
+    </ol>
+  );
+};
+```
+
+### 7.2. Armazenando Preferências
+
+- Salve a escolha de idioma do seu usuário em um **cookie** ou **sessão**.
+- Na próxima vez que ele visitar seu site, você pode carregar automaticamente seu idioma preferido.
+
+---
+
+## 8. Construindo Backlinks Locais
+
+**Backlinks** (links de sites externos para o seu) continuam sendo um fator importante de SEO. Quando você executa um site multilíngue, considere:
+
+- Entrar em contato com sites de notícias locais, blogs ou fóruns. Por exemplo, um domínio `.fr` apontando para sua subpasta francesa pode aumentar seu SEO local francês.
+- Monitorar backlinks por idioma para ver quais regiões precisam de mais esforços de PR/marketing.
+
+---
+
+## 9. Monitorando & Mantendo Seu Site Multilíngue
+
+### 9.1. Google Analytics & Search Console
+
+- Segmente seus dados para cada diretório de idioma (`/en/`, `/fr/`, `/es/`).
+- Fique atento a **erros de rastreamento**, **sinalizações de conteúdo duplicado**, e **problemas de indexação** com base em cada idioma.
+
+### 9.2. Atualizações Regulares de Conteúdo
+
+- Mantenha as traduções atualizadas. Se você alterar uma descrição de produto em inglês, atualize em francês, espanhol, etc.
+- Traduções desatualizadas podem confundir os clientes e prejudicar a confiança do usuário.
+
+---
+
+## 10. Armadilhas Comuns a Evitar
+
+1. **Conteúdo Traduzido por Máquinas**
+   Traduções automatizadas sem revisão humana podem estar repletas de erros.
+
+2. **Tags `hreflang` Incorretas ou Ausentes**
+   Os mecanismos de busca não conseguem determinar as versões de idioma por conta própria se suas tags estiverem incompletas ou com códigos errados.
+
+3. **Mudança de Idioma Apenas via JavaScript**
+   Se o Google não conseguir rastrear URLs únicos para cada idioma, suas páginas podem não aparecer nos resultados de pesquisa locais corretos.
+
+4. **Ignorar Nuances Culturais**
+   Uma piada ou frase que funciona em um país pode ser ofensiva ou sem sentido em outro.
+
+---
+
+## Conclusão
+
+Tornar seu site multilíngue envolve mais do que apenas traduzir texto. Trata-se de estruturar URLs de forma eficaz, usar tags `hreflang` para ajudar os mecanismos de busca a servir a versão correta, e proporcionar uma experiência excepcional ao usuário, com visuais localizados, seletores de idiomas e navegação consistente. Seguir estas melhores práticas o preparará para o sucesso em mercados globais, aumentará a satisfação do usuário e, em última análise, fornecerá melhores resultados de SEO em várias regiões.
+
+Se você está usando Next.js (particularmente Router App no Next.js 13+), uma ferramenta como **Intlayer** pode simplificar todo esse processo. Ela ajuda com tudo, desde a geração de sitemaps localizados até o manuseio automático de links `hreflang`, detecção de idiomas e muito mais, para que você possa se concentrar em criar conteúdo multilíngue de qualidade.
+
+**Pronto para ir global?** Comece a implementar essas estratégias de SEO e i18n agora e veja novos visitantes de todo o mundo descobrirem e se engajarem com seu site!

package/blog/pt/intlayer_with_i18next.md

@@ -0,0 +1,162 @@
+---
+createdAt: 2024-12-24
+updatedAt: 2025-06-29
+title: Intlayer e i18next
+description: Integre o Intlayer com o i18next para uma internacionalização ideal. Compare os dois frameworks e aprenda como configurá-los juntos.
+keywords:
+  - Intlayer
+  - i18next
+  - Internacionalização
+  - i18n
+  - Localização
+  - Tradução
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - blog
+  - intlayer-with-i18next
+---
+
+# Internacionalização com Intlayer e i18next
+
+i18next é um framework de internacionalização (i18n) de código aberto projetado para aplicações JavaScript. É amplamente utilizado para gerenciar traduções, localização e troca de idiomas em projetos de software. No entanto, possui algumas limitações que podem complicar a escalabilidade e o desenvolvimento.
+
+Intlayer é outro framework de internacionalização que aborda essas limitações, oferecendo uma abordagem mais flexível para declaração e gerenciamento de conteúdo. Vamos explorar algumas diferenças principais entre i18next e Intlayer, e como configurar ambos para uma internacionalização ideal.
+
+## Intlayer vs. i18next: Diferenças Chave
+
+### 1. Declaração de Conteúdo
+
+Com o i18next, os dicionários de tradução devem ser declarados em uma pasta específica, o que pode complicar a escalabilidade da aplicação. Em contraste, o Intlayer permite que o conteúdo seja declarado dentro do mesmo diretório que seu componente. Isso possui várias vantagens:
+
+- **Edição de Conteúdo Simplificada**: Os usuários não precisam procurar o dicionário correto para editar, diminuindo a chance de erros.
+- **Adaptação Automática**: Se um componente muda de localização ou é removido, o Intlayer detecta e se adapta automaticamente.
+
+### 2. Complexidade de Configuração
+
+Configurar o i18next pode ser complexo, especialmente ao integrar com componentes do lado do servidor ou ao configurar middleware para frameworks como Next.js. O Intlayer simplifica esse processo, oferecendo uma configuração mais direta.
+
+### 3. Consistência dos Dicionários de Tradução
+
+Garantir que os dicionários de tradução sejam consistentes em diferentes idiomas pode ser desafiador com o i18next. Essa inconsistência pode levar a falhas na aplicação se não for tratada adequadamente. O Intlayer aborda isso aplicando restrições ao conteúdo traduzido, garantindo que nenhuma tradução seja perdida e que o conteúdo traduzido seja preciso.
+
+### 4. Integração com TypeScript
+
+O Intlayer oferece melhor integração com TypeScript, permitindo sugestões automáticas de conteúdo em seu código, aumentando, assim, a eficiência do desenvolvimento.
+
+### 5. Compartilhamento de Conteúdo entre Aplicações
+
+O Intlayer facilita o compartilhamento de arquivos de declaração de conteúdo entre várias aplicações e bibliotecas compartilhadas. Esse recurso torna mais fácil manter traduções consistentes em uma base de código maior.
+
+## Como Gerar Dicionários do i18next com Intlayer
+
+### Configurando o Intlayer para Exportar Dicionários do i18next
+
+> Notas Importantes
+
+> A exportação de dicionários do i18next está atualmente em beta e não garante uma compatibilidade 1:1 com outros frameworks. Recomenda-se aderir a uma configuração baseada no Intlayer para minimizar problemas.
+
+Para exportar dicionários do i18next, você precisa configurar o Intlayer adequadamente. Abaixo está um exemplo de como configurar o Intlayer para exportar tanto os dicionários do Intlayer quanto do i18next.
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  content: {
+    // Indica que o Intlayer irá exportar tanto os dicionários do Intlayer quanto do i18next
+    dictionaryOutput: ["intlayer", "i18next"],
+    // Caminho relativo a partir da raiz do projeto até o diretório onde os dicionários i18n serão exportados
+    i18nextResourcesDir: "./i18next/dictionaries",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  content: {
+    // Indica que o Intlayer irá exportar tanto os dicionários do Intlayer quanto do i18next
+    dictionaryOutput: ["intlayer", "i18next"],
+    // Caminho relativo a partir da raiz do projeto até o diretório onde os dicionários i18n serão exportados
+    i18nextResourcesDir: "./i18next/dictionaries",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  content: {
+    // Indica que o Intlayer irá exportar tanto os dicionários do Intlayer quanto do i18next
+    dictionaryOutput: ["intlayer", "i18next"],
+    // Caminho relativo a partir da raiz do projeto até o diretório onde os dicionários i18n serão exportados
+    i18nextResourcesDir: "./i18next/dictionaries",
+  },
+};
+
+module.exports = config;
+```
+
+Ao incluir 'i18next' na configuração, o Intlayer gera dicionários dedicados do i18next além dos dicionários do Intlayer. Observe que remover 'intlayer' da configuração pode quebrar a compatibilidade com React-Intlayer ou Next-Intlayer.
+
+### Importando Dicionários na Sua Configuração do i18next
+
+Para importar os dicionários gerados na sua configuração do i18next, você pode usar 'i18next-resources-to-backend'. Aqui está um exemplo de como importar seus dicionários do i18next:
+
+```typescript fileName="i18n/client.ts" codeFormat="typescript"
+// i18n/client.ts
+
+import i18next from "i18next";
+import resourcesToBackend from "i18next-resources-to-backend";
+
+i18next
+  // Sua configuração do i18next
+  .use(
+    resourcesToBackend(
+      (language: string, namespace: string) =>
+        import(`../i18next/dictionaries/${language}/${namespace}.json`)
+    )
+  );
+```
+
+```javascript fileName="i18n/client.mjs" codeFormat="esm"
+// i18n/client.mjs
+
+import i18next from "i18next";
+import resourcesToBackend from "i18next-resources-to-backend";
+
+i18next
+  // Sua configuração do i18next
+  .use(
+    resourcesToBackend(
+      (language, namespace) =>
+        import(`../i18next/dictionaries/${language}/${namespace}.json`)
+    )
+  );
+```
+
+```javascript fileName="i18n/client.cjs" codeFormat="commonjs"
+// i18n/client.cjs
+
+const i18next = require("i18next");
+const resourcesToBackend = require("i18next-resources-to-backend");
+
+i18next
+  // Sua configuração do i18next
+  .use(
+    resourcesToBackend(
+      (language, namespace) =>
+        import(`../i18next/dictionaries/${language}/${namespace}.json`)
+    )
+  );
+```