Forem: Francisco GSilva

Real Bilingual Blog Refactor: Routes, hreflang, and Consistent SEO

Francisco GSilva — Wed, 11 Feb 2026 12:11:54 +0000

Real Bilingual Blog Refactor: Routes, hreflang, and Consistent SEO

Building a bilingual blog is not just translation work. If route architecture, canonical strategy, and navigation are not aligned, you get duplicate content, indexing confusion, and users landing in mixed-language sections.

This refactor solved that from end to end. Here is the practical walkthrough.

Initial Problem

We had clear symptoms:

/blog was mixing Spanish and English posts,
old non-localized URLs were still active,
direct URL visitors did not get consistent language behavior,
Search Console showed canonical conflicts and duplicates.

Goal: language-consistent UX and crawl-friendly SEO.

Architecture Decisions

We standardized around five rules:

Language-first routes: /{lang}/...
Smart redirects for generic routes (/, /blog, /tags)
Per-post hreflang + x-default
Language preference cookie (site_lang)
Localized pages for home, tags, and category hubs

Step 1: Localized Pages

We implemented language-aware pages:

src/pages/[lang]/index.astro
src/pages/[lang]/blog/[...slug].astro
src/pages/[lang]/blog/index.astro
src/pages/[lang]/blog/category/index.astro
src/pages/[lang]/tags/index.astro
src/pages/[lang]/tags/[tag].astro

This removes ambiguity and makes language explicit in every route.

Step 2: Middleware Redirect Strategy

Middleware now resolves language from cookie + Accept-Language, then redirects generic routes.

Simplified logic:

const preferredLang = cookieLang ?? detectLangFromHeader(acceptLanguageHeader);

if (normalizedPath === "/") {
  return Response.redirect(new URL(`/${preferredLang}/`, url.origin), 302);
}

if (normalizedPath === "/blog") {
  return Response.redirect(new URL(`/${preferredLang}/blog/`, url.origin), 302);
}

Result: no more mixed-language listing pages.

Step 3: Canonical and hreflang

We extended SEO metadata to include language alternates:

export interface LanguageAlternateEntry {
  lang: string;
  url: string;
}

Per post, alternates are computed by translationKey and include x-default.

const alternates = translations.map((translation) => ({
  lang: translation.data.lang,
  url: `${siteUrl}${translation.data.lang}/blog/${translation.id}/`,
}));
alternates.push({ lang: "x-default", url: `${siteUrl}en/blog/${defaultId}/` });

This gives search engines explicit language mapping and reduces canonical ambiguity.

Step 4: Navigation Consistency

The header was updated to preserve language context:

Home -> /${lang}
Tags -> /${lang}/tags
Categories -> /${lang}/blog/category

We also added an explicit ES | EN switcher and persist user choice via cookie.

Step 5: Remove Duplicate "Related" UX

Some migrated posts had both:

markdown “Related” link list,
visual related-posts component.

That created duplicated sections and visual noise. We removed markdown duplicates and kept the component-based related cards.

Step 6: Translation Coverage Report

To prevent ES/EN drift, we added a coverage report:

pnpm run seo:report-translations

Output:

docs/seo/translation-coverage.md

This catches incomplete translation keys before release.

Step 7: QA Checklist After Refactor

[ ] /blog redirects to /{lang}/blog/
[ ] /tags redirects to /{lang}/tags/
[ ] post canonical matches localized URL
[ ] hreflang includes ES/EN + x-default
[ ] no mixed-language listing pages
[ ] build passes cleanly

Common Mistakes in Bilingual Refactors

Translating content but keeping non-localized URLs.
Localized routes without metadata parity.
Navigation that breaks language context.
Redirect chains without a clear policy.
No automated translation coverage audit.

Publishing Opportunities From This Refactor

This refactor itself can become a technical series:

Language route architecture in Astro.
Practical international SEO: canonical + hreflang.
Migration strategy that preserves indexing stability.

Close

The biggest win was not “having two languages.” The real win was consistency across user navigation, metadata, and crawl behavior.

If you are planning a similar migration, do not start with translation copywriting. Start with route architecture, canonical strategy, and redirect behavior.

Configurar un nuevo sitio web en NGINX

Francisco GSilva — Wed, 11 Feb 2026 02:57:42 +0000

Configurar un nuevo sitio web en NGINX

Seguir los siguientes comando:

crear folder del sitio
sudo mkdir -p /var/www/{your-domain}/
Asignamos el usuario dueño del folder
sudo chown -R $USER:$USER /var/www/{your-domain}/
Asignamos permisos
sudo chmod -R 755 /var/www/{your-domain}/
Creamos un index.html file a modo de prueba
sudo nano /var/www/{your-domain}/index.html
Contenido del archivo index.html

<html>
    <head>
        <title>Welcome to your-domain!</title>
    </head>
    <body>
        <h1>Success!  The your-domain server block is working!</h1>
    </body>
</html>

Para que Nginx pueda servir este contenido, es necesario crear un server block con las directivas correctas. En lugar de modificar el archivo de configuración predeterminado directamente, hagamos uno nuevo en /etc/nginx/sites-available/{your-domain}:

sudo nano /etc/nginx/sites-available/{your-domain}

El contenido del archivo de configuración:

server {
        listen 80;
        listen [::]:80;

        root /var/www/your_domain;
        index index.html index.htm index.nginx-debian.html;

        server_name your_domain www.your_domain;

        location / {
                try_files $uri $uri/ =404;
        }
}

A continuación, vamos a habilitar el archivo creando un enlace desde este al directorio sites-enabled, del cual Nginx lee durante el inicio:

sudo ln -s /etc/nginx/sites-available/your_domain /etc/nginx/sites-enabled/

NOTA: Nginx utiliza una práctica común llamada enlaces simbólicos, o symlinks, para rastrear cuáles de tus bloques de servidor están habilitados. Crear un symlink es como crear un acceso directo en el disco, de modo que más tarde podrías eliminar el acceso directo del directorio sites-enabled mientras mantienes el bloque de servidor en sites-available si quisieras habilitarlo.

Para evitar un posible problema de memoria del hash bucket que puede surgir al agregar nombres de servidor adicionales, es necesario ajustar un solo valor en el archivo /etc/nginx/nginx.conf. Abre el archivo:

sudo nano /etc/nginx/nginx.conf

Encuentra la directiva server_names_hash_bucket_size y elimina el símbolo # para descomentar la línea. Si estás usando nano, puedes buscar rápidamente palabras en el archivo presionando CTRL y w.

Verifica que el archivo de configuración no contenga errores: sudo nginx -t

Reiniciamos el servicio de nginx sudo systemctl restart nginx

Subtitulo

Otro subtitulo

Fix to Key

Francisco GSilva — Wed, 11 Feb 2026 02:49:56 +0000

Fix to Key

error: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY A8580BDC82D3DC6C

solución:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys A8580BDC82D3DC6C

Set Up a New Website in NGINX

Francisco GSilva — Wed, 11 Feb 2026 02:49:55 +0000

Set Up a New Website in NGINX

Run the following commands:

Create the site folder
sudo mkdir -p /var/www/{your-domain}/
Set your user as the folder owner
sudo chown -R $USER:$USER /var/www/{your-domain}/
Set permissions
sudo chmod -R 755 /var/www/{your-domain}/
Create a test index.html file
sudo nano /var/www/{your-domain}/index.html
index.html file content

<html>
    <head>
        <title>Welcome to your-domain!</title>
    </head>
    <body>
        <h1>Success!  The your-domain server block is working!</h1>
    </body>
</html>

For NGINX to serve this content, create a new server block with the right directives. Instead of editing the default config directly, create a new file at /etc/nginx/sites-available/{your-domain}:

sudo nano /etc/nginx/sites-available/{your-domain}

Configuration file content:

server {
        listen 80;
        listen [::]:80;

        root /var/www/your_domain;
        index index.html index.htm index.nginx-debian.html;

        server_name your_domain www.your_domain;

        location / {
                try_files $uri $uri/ =404;
        }
}

Enable the file by creating a symlink to sites-enabled, which NGINX reads on startup:

sudo ln -s /etc/nginx/sites-available/your_domain /etc/nginx/sites-enabled/

NOTE: NGINX uses symbolic links (symlinks) to track which server blocks are enabled. Creating a symlink is like creating a shortcut: later, you can remove that shortcut from sites-enabled while keeping the original config in sites-available.

To avoid potential hash bucket memory issues when adding additional server names, update one value in /etc/nginx/nginx.conf. Open the file:

sudo nano /etc/nginx/nginx.conf

Find the server_names_hash_bucket_size directive and remove # to uncomment the line. If you use nano, press CTRL + w to search quickly.

Check for config errors: sudo nginx -t

Restart NGINX: sudo systemctl restart nginx