DEV Community: Ifeanyi Chima

How to translate MDN web docs to spanish.

Ifeanyi Chima — Thu, 03 Sep 2026 23:21:22 +0000

Good day, for the past 3 weeks I have been busy translating the popular documentation platform known as MDN web docs into the Spanish version, to help Spanish-speaking readers as it had been outdated for years with respect to the English version.

This has been part of my open-source journey. In this article, I want to talk about the process, to enable future contributors to seamlessly contribute one day.

Here are the rules to follow when trying to do the Spanish-translation work. Everything that I am going to write here is already mentioned inside of the rules.

So, what is our job here ?

There's a page in English for example: Django's "Admin site" feature.
There's already a Spanish version of that page, but it's old and out of date.
Your job is to go through the whole Spanish file, compare it to the whole English file, and rewrite/update it so it matches: same sections, same order, nothing left in English

Here is one rule to just bear in mind

is this text something a human reads (translate it) or something the code/interpreter looks up by exact name (leave it untouched)

File Paths

This is the most important one; File paths (bolded or inline) are never translated. It stays the same. Below, we will discuss the only thing that changes, which is en-US to es

English: docs/Web/JavaScript/Reference/Global_Objects/Object/assign

Spanish: docs/Web/JavaScript/Reference/Global_Objects/Object/assign

Front-matter

Final front-matter should only contain: title, slug, l10n.sourceCommit (plus short-title when the English file has one).
Remove page-type, sidebar, original_slug.
title (and short-title): translate to Spanish.
slug: These are file paths, not visible text, so they stay exactly as in English do not translate.
l10n.sourceCommit: set to the exact SHA given for that English source commit.

Links

External links: These are links point to external web pages and they should be left as is. For example: https://validator.w3.org/ or https://developer.flutterwave.com/docs/testing

Internal links: All the internal links that point to pages with in the MDN web docs website have to be changed from /en-US/ to /es/.

For example:

Original (English source):

/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign

This has to be changed to point to a spanish file now.

/es/docs/Web/JavaScript/Reference/Global_Objects/Object/assign

Link Text: (ONLY the visible label) gets translated when it's an internal MDN link.

For example

Original (English source):

[Object basics](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics)

We have to translate The link text "Object basics" to "Fundamentos de objetos"

Translated (Spanish):

[Fundamentos de objetos](/es/docs/Learn_web_development/Core/Scripting/Object_basics)

Anchors: when you have an anchor like this, #heading_about_a_paragraph. Two things are involved:

You need to check if that section that the anchor is referring to exists.
If it exists, then you should translate it to Spanish #encabezado_sobre_un_párrafo

Bold / italics

Keep the bold/italic markers in the same place, only translate the text content.
Text content that were bold or italics in English stay bold or italics in Spanish.

Original (English source):

_this is supposed to be italic_ and **this is supposed to be bold**

Translated (Spanish):

_esto se supone que debe estar en cursiva_ and **esto se supone que debe estar en negrita**

Image(s)

Never copy images into the files/es/ folder because the build pulls them from the English folder automatically. Just leave the image file path as is
Only the alt text (the [...] part) gets translated; the filename or file path stays exactly as-is.

For example:

Original (English source)

![Prototype chain for myObject](myobject-prototype-chain.svg)

Translated (Spanish)

![Cadena de prototipos para myObject](myobject-prototype-chain.svg)

Callouts

In GitHub markdown, callouts such as [!NOTE] and [!WARNING] stay untranslated because translating them breaks the styled box.
ONLY the user-facing text content contained within the box gets translated.

For example,

Original (English source)

>[!NOTE]
> See also the [glossary entry on API](/en-US/docs/Glossary/API) for more information.

Translated (Spanish)

>[!NOTE]
> Consulta también la [entrada del glosario sobre API](/es/docs/Glossary/API) para más información.

Notice: [!NOTE] remains untouched

Code

Plain Code blocks: These are code blocks that contain only literal data: no comments, no prose mixed in so there's nothing to translate at all.

https://example.com/articles/
https://example.com/articles/23
https://example.com/articles/?page=2

This stays exactly the same in the Spanish file — same URLs, same formatting, no changes whatsoever. There's no comment explaining anything and no prose sentence inside it.

name
age
city
greet

These are actual JavaScript property names being listed for the reader to look at, not descriptive text, so translating "city" to "ciudad" or "age" to "edad" would misrepresent what the code actually contains.

HTML table structure:
Table tags (<table>, <tr>, <th>, etc.) stay exactly the same, only the visible text inside is translated.

For example:

Original (English source):

<table class="properties">
  <tbody>
    <tr>
      <th scope="row">Prerequisites</th>
      <td>
        A basic understanding of <a href="/en-US/docs/Learn_web_development/Core/Scripting">JavaScript basics</a>.
      </td>
    </tr>
    <tr>
      <th scope="row">Objective</th>
      <td>To understand JavaScript's prototype-based inheritance model.</td>
    </tr>
  </tbody>
</table>

Translated (Spanish):

<table class="properties">
  <tbody>
    <tr>
      <th scope="row">Prerrequisitos</th>
      <td>
        Un entendimiento básico de <a href="/es/docs/Learn_web_development/Core/Scripting">los fundamentos de JavaScript</a>.
      </td>
    </tr>
    <tr>
      <th scope="row">Objetivo</th>
      <td>Comprender el modelo de herencia basado en prototipos de JavaScript.</td>
    </tr>
  </tbody>
</table>

Kumascript macros {{...}}

Macro names and their arguments (page paths) are never translated. The macro names such as (NextMenu, PreviousMenuNext) stay in English because they're internal MDN template functions, not prose.
{{glossary("term")}}: if the English term doesn't naturally read well in Spanish, add a second argument with the translated display text — {{glossary("term", "término")}}. If the term is used as-is in Spanish (e.g. HTTP, JavaScript, Python), leave it with no second argument.
Navigation macros ({{NextMenu(...)}}, {{PreviousMenuNext(...)}}) always left fully untouched whether in English or Spanish.

{{NextMenu("Learn_web_development/Core/Scripting/Object_prototypes", "Learn_web_development/Core/Scripting")}}

{{PreviousMenuNext("Learn_web_development/Core/Scripting/Object_prototypes", "Learn_web_development/Core/Scripting/Object_building_practice", "Learn_web_development/Core/Scripting")}}

Headings

Translate headings to match the reference heading list given in the issue, using consistent verb style (gerund/imperative) across the doc. When you finish translating, review your work and make sure you have same headings, same order, same structure as the English source and Nothing is left untranslated

English (Original Source)

## Summary
## Basics: anatomy of a URL
## Scheme
## Authority
## Path to resource
## Parameters
## Anchor
## How to use URLs
## Absolute URLs vs. relative URLs
## URL usernames and passwords
## Semantic URLs
## See also

Translated (Spanish)

## Resumen
## Conceptos básicos: anatomía de una URL
## Esquema
## Autoridad
## Ruta al recurso
## Parámetros
## Ancla
## Cómo utilizar las URL
## URL absolutas frente a URL relativas
## Nombres de usuario y contraseñas en las URL
## URL semánticas
## Véase también

Watch for accented characters affecting auto-generated anchor targets (e.g. "Validación" becomes anchor validación_html, not validacion_html) because a missing accent in a link breaks the anchor.

Link: /es/docs/Learn_web_development/Core/Forms/Form_validation#validación_html

For example;

English (Original source)

## Validation HTML

Here's a small but easy-to-miss detail about headings and links. When MDN builds a page, it auto-generates an anchor ID for every heading by lowercasing the text and replacing spaces with underscores. The catch is that it keeps accented characters exactly as they are.

Translated Spanish

## Validación HTML

Aquí hay un detalle pequeño pero fácil de pasar por alto sobre los encabezados y los enlaces. Cuando MDN construye una página, genera automáticamente un ancla para cada encabezado convirtiendo el texto a minúsculas y reemplazando los espacios con guiones bajos. La particularidad es que mantiene los caracteres acentuados exactamente como están.

Comments

Comments inside of Code blocks

This has two (2) cases:

A comment that is explaining something to the user (reader) should be translated.
A comment that does not add any additional useful information should be discarded.

Useful comment(s)

A comment explaining something (translate it):
This comment is real prose explaining why the line exists or what it does. A Spanish-speaking reader benefits from having this translated

English (Original Source)

# Number of visits to this view, as counted in the session
num_visits = request.session.get('num_visits', 0)

Translated (Spanish)

# Número de visitas a esta vista, contado en la sesión
num_visits = request.session.get('num_visits', 0)

Throwaway comment(s)

Example 1

INSTALLED_APPS = [
    # ...
    'django.contrib.sessions',
]

Here, # ... isn't explaining anything — it's just a visual placeholder telling the reader "there's more code here we're not showing." There's no real content to translate; translating ... doesn't mean anything different in Spanish. Best left as-is.

Example 2

const wheels = 'alloy'; // or comment

This kind of comment is minor, vague, and doesn't add much context either way, so it's genuinely a coin-flip: leave it in English since it's a throwaway aside, or translate it for full consistency with the rest of the document.

Keywords, Variables, Functions:

DO NOT TRANSLATE ANY OF THESE

Variable names — e.g. numOfVisits, myCar, count

Function/method names — e.g. getPrototypeOf(), index()

Class names — e.g. Person, Author

Property/dictionary keys — e.g. city, wheels, my_car['wheels']

Exception names — e.g. KeyError

Boolean values (true, false): remain untranslated in both English and Spanish

English (Original Source)

// Uses 'toString()' by default, returns true

Translated (Spanish)

// Usa 'toString()' por defecto, devuelve true

Methods

Method names mentioned inside comments stay untouched.

English (Original Source)

// Calls 'getPrototypeOf()' to find the parent

Translated (Spanish)

// Llama a 'getPrototypeOf()' para encontrar al padre

Console.log()

There are two (2) incidents here:

For literal strings printed to the user, you should translate it. An example is

English (Original Source):

console.log("Greetings from Madrid");

Translated Spanish:

console.log("Saludos desde Madrid");

short/generic literal, here it's a judgment call, and the practical approach is to flag it for the reviewer

Example:

function greet() {
  console.log("hello!");
}

Pluralization

If translating a word breaks a language feature (e.g. pluralization), adapt the word so the mechanism still works (e.g. "time" becomes "vece").

"time" plural form is "times" in English, but the literal spanish translation would be wrong (broken) spanish.

if we were to follow a literal translation of "time" into spanish "vez" literal plural translation "vezs" (which is wrong spanish)

"vez" correct plural form in spanish is "vece".

num_visits = 3, Here, pluralize looks at num_visits and, if it's more than 1, appends an "s" to whatever comes right before the template tag — turning "time" into "times".

English (Original Source)

You have visited this page {{ num_visits }} time{{ num_visits|pluralize }}.

Adapted translation (mechanism still works):

Has visitado esta página {{ num_visits }} vece{{ num_visits|pluralize }}.

More Information

Run Prettier on the finished file, when you are done translating.

npx prettier --write files/es/learn_web_development/core/scripting/object_prototypes/index.md

Check for invisible/zero-width characters (e.g. using a script scanning for U+200B, U+200C, U+200D, U+FEFF)

import unicodedata
import sys

INVISIBLE_CHARS = (0x200B, 0x200C, 0x200D, 0xFEFF)

def check_file(path):
    with open(path, encoding="utf-8") as f:
        for line_number, line in enumerate(f, 1):
            found = [
                unicodedata.name(char, "?")
                for char in line
                if ord(char) in INVISIBLE_CHARS
            ]
            if found:
                print(line_number, found, repr(line[:40]))

if __name__ == "__main__":
    check_file(sys.argv[1])

Thank you and please follow me.

How to setup WikiEduDashboard for OSS contribution

Ifeanyi Chima — Sun, 30 Aug 2026 15:22:12 +0000

1. Problem Statement

I wanted to contribute to an open source project called WikiEduDashboard, a web application built by Wiki Education. It helps instructors and program leaders run Wikipedia-editing classes and campaigns: students join a course, make edits to Wikipedia, and the dashboard tracks their work.

To contribute code to this project, I first need a working copy of it running on my own PC. This is called a "local development environment." Without it, I can't test any changes I make before sending them back to the project.

The problem: this project was built with tools that work best on Mac or Linux, not on plain Windows. So the first challenge wasn't even the project itself, it was figuring out how to run a Linux-friendly project on a Windows PC.

2. The Solution (High Level)

Instead of fighting Windows directly, we used a feature built into Windows called WSL (Windows Subsystem for Linux). WSL lets a real Linux system (Ubuntu, in our case) run inside Windows, side by side with your normal Windows apps. It's not a separate computer or a virtual machine you have to babysit, it just works like an extra terminal environment on the same PC.

Once inside Ubuntu, we could follow the project's official setup instructions exactly as written, since those instructions assume a Mac or Linux machine.

The overall plan looked like this:

Get a Linux environment running on Windows (WSL + Ubuntu)
Get a personal copy of the project's code (fork it on GitHub, then clone it)
Install the programming language the project is built with (Ruby)
Run the project's automated setup script, which installs the rest of the required tools (database, background job system, etc.)
Start the actual application and view it in a browser
Build the frontend (the visual, interactive part of the site)
Set up an editor (VS Code) that can actually see and edit the code living inside Ubuntu

3. Step by Step: What We Did and Why

Step 1: Install WSL and Ubuntu

What: WSL is a Windows feature that runs a real Linux distribution (we used Ubuntu) inside Windows.

Why we needed it: WikiEduDashboard's setup script only officially supports Debian-based Linux (like Ubuntu), Fedora, and macOS. Plain Windows isn't supported well: things like Ruby, Redis, and MySQL are much harder to install and configure correctly on native Windows.

Command used (from PowerShell, as Administrator):

wsl --install

After installing, opening "Ubuntu" from the Start menu gives a terminal prompt that looks like this:

adminuser@DESKTOP-OF73031:~$

That ~ symbol means "home folder", it's the starting point for everything else we did.

Step 2: Confirm Git Was Available

What: Git is a tool used to download ("clone") and manage code from GitHub.

Why: We need it to grab a copy of the project's code onto our PC.

git --version

This returned git version 2.43.0, confirming git was already installed inside Ubuntu.

Step 3: Fork and Clone the Repository

We forked the project on GitHub first (via the browser, clicking the "Fork" button on the project's page), then cloned our fork:

git clone https://github.com/YOUR_USERNAME/WikiEduDashboard.git
cd WikiEduDashboard

Step 4: Install Ruby

What is Ruby? Ruby is the programming language WikiEduDashboard's backend (the "engine" of the app) is written in, specifically using a framework called Ruby on Rails.

Why we needed a specific version: The project requires Ruby 3.4.8 exactly. Running the setup script without Ruby installed gave this error:

ruby: command not found
Ruby-3.4.8 not found. Please install ruby-3.4.8 and run this script again.

How we installed it: using a tool called RVM (Ruby Version Manager), which makes it easy to install and switch between specific Ruby versions.

Here is how we install the RVM tool, copy and paste this block of command into your ubuntu terminal

sudo apt update
sudo apt install -y gnupg2
gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
curl -sSL https://get.rvm.io | bash -s stable
source /home/adminuser/.rvm/scripts/rvm
rvm install "ruby-3.4.8"

Confirming it worked:

ruby -v

Result: ruby 3.4.8 (2025-12-17 revision 995b59f666) +PRISM [x86_64-linux]

Step 5: Run the Automated Setup Script

The project ships with a Python script (setup.py) that automates installing everything else the project needs: gems (Ruby's package system), a database (MySQL/MariaDB), configuration files, and JavaScript packages.

Why: Doing all of this by hand (the "manual setup" path in the project's docs) is long and error-prone. The script does it consistently.

python3 setup.py

This script:

Installed Ruby "gems" (Ruby's version of code libraries/packages)
Created configuration files (config/application.yml and config/database.yml) from example templates
Created the development and test databases
Created a MySQL user for the app to use
Ran database migrations (setting up the actual tables the app needs)
Installed JavaScript packages using Yarn (a package manager for frontend/JavaScript code, similar in purpose to gem for Ruby)

At the end, it printed:

Your development environment setup is complete.

Step 6: Start Redis

What is Redis? Redis is a fast, lightweight in-memory data store. In this project, it's used by a background job system called Sidekiq, which handles tasks like scheduled updates and syncing data, things that shouldn't slow down the main website while they run.

Why it matters: without Redis running, features that rely on background jobs (some Wikipedia-editing features especially) won't work properly.

redis-server

We got an error saying the port was already in use:

Could not create server TCP listening socket *:6379: bind: Address already in use

This actually meant Redis was already running in the background (likely started automatically during setup). We confirmed this instead of restarting it:

redis-cli ping

Result: PONG, meaning Redis was alive and responding correctly.

Step 7: Start the Rails Server

What: This starts the actual backend server, the part that listens for requests and serves the website.

rails s

Once running, it showed:

* Listening on http://127.0.0.1:3000
Use Ctrl-C to stop

This means the app was now reachable at http://localhost:3000 in a browser. This terminal window needs to stay open and running the whole time the app is in use.

Step 8: Open the Frontend Build

open a second Ubuntu terminal window (leaving the first one running rails s untouched), move into the project folder, and run yarn start, see example below:

cd WikiEduDashboard
yarn start

This compiles the frontend and also watches for future changes, automatically rebuilding when files are edited.

After this finished, refreshing http://localhost:3000 showed the actual dashboard homepage, fully styled and working, logged in as Chimaifeanyi29.

Step 9: Set Up VS Code to Edit the Code

The problem: the project's code physically lives inside the Ubuntu (WSL) filesystem, not in a normal Windows folder. Opening VS Code the usual way on Windows wouldn't show the right files.

The solution: VS Code has a "Remote - WSL" extension that lets it connect directly into the Ubuntu environment.

Steps:

Install VS Code normally on Windows (if not already installed)
Inside VS Code, go to the Extensions tab and install the extension called "WSL" (by Microsoft)
From inside the Ubuntu terminal, inside the project folder, run:

code .

This opens VS Code on the Windows desktop, but connected directly to the Ubuntu filesystem, shown by a "WSL: Ubuntu" indicator in the bottom-left corner of the editor.

4. Summary: What's Currently Running

At the end of this session, the local development setup consists of three things running at once:

Component	Purpose	Where it runs
`rails s`	The backend server (handles requests, talks to the database)	Terminal 1
`yarn start`	Builds and watches the frontend (JavaScript/React code)	Terminal 2
Redis (background)	Powers background jobs via Sidekiq	Runs automatically

The app is reachable in a browser at:

http://localhost:3000

5. Key Terms Explained (Quick Reference)

WSL (Windows Subsystem for Linux): A way to run real Linux (Ubuntu, here) inside Windows without a separate computer or full virtual machine.
Fork: Your own personal copy of someone else's GitHub project, needed before you can propose changes back to it.
Clone: Downloading a copy of a GitHub project's code onto your own machine.
Ruby / Ruby on Rails: The programming language and web framework the backend of this project is built with.
RVM: A tool for installing and managing specific versions of Ruby.
Gems: Ruby's term for external code packages/libraries.
Yarn: A package manager for JavaScript, used here to install and build the frontend.
Redis: A fast in-memory data store, used to support background job processing.
Sidekiq: A background job system (built on Ruby) that uses Redis, used for scheduled tasks like data syncing.
Rails server (rails s): The command that starts the actual running web application.
manifest.json: A file generated by the frontend build process that tells the backend where compiled frontend assets live.

I solved a 5 year old bug

Ifeanyi Chima — Thu, 30 Jul 2026 22:48:44 +0000

This is a submission for DEV's Summer Bug Smash: Smash Stories powered by Sentry.

Introduction

Let me start by saying I am an Open-source contributor at Mozilla, I am trying to get better as a software engineer. I will be using the words Site or Tile interchangeably, they mean the same thing.

Bug Report

The title of the bug report was "Cannot remove amazon.com from top sites list" on Bugzilla and I believe it really captures the pain-point that users experienced because of the bug.

In this bug report the user is complaining that he cannot remove amazon.com from Top Sites in the New tab page of his Mozilla Firefox browser.

Background

A little back-story of what Top Sites, New tab page and Places is:

Top Sites is that grid of website shortcuts you see on Firefox's New Tab Page. It shows the sites you visit most often, plus some sponsored tiles (called "spocs," short for sponsored content) that Mozilla partners provide. The image below shows a row of Top Sites on the New Tab page.

New tab page is the page that opens when you open a new tab or click the home button.

Places is a SQLite database that Firefox uses to store browsing history.

The Problem

Imagine you open a new tab in Firefox and see a grid of your most-visited websites (called "Top Sites"). amazon.com keeps showing up there, even though you never visit it and you keep trying to delete it.

You right-click on the Amazon icon, click "Delete from History," but... nothing happens. It just sits there, refusing to leave. You try again. Still there. You try "Dismiss." Still there. It's like a stubborn guest who won't leave your house.

Why This Happens

Firefox's Top Sites can come from three places:

Your actual browsing history (sites you really visited)
Pinned sites (sites you manually pinned to stay there)
Default/curated sites (sites Firefox puts there automatically, like Amazon, because they think you might want them)

Stay with me and we would find out which one of these is the culprit.

Understanding the Bug (Part A)

Investigation:

By reading through the thread on the bug report, I discovered a trick other users on the thread had tried

one user on the thread had the idea of changing the URL and then the problem went away, but after a new firefox release Firefox 82.0 (64-bit) the trick could no longer work.

Reproducing:

To reproduce the bug locally, I had to visit https://amazon.com multiple times (up to 20 times) on my local PC so that I can get amazon.com to show up as a Top Site on my New Tab page.

Reviewer Feedback

My first attempt was to block the url whenever a user clicked "Delete History" so that it will never show up again in Top Sites.

mak (a mozilla engineer) pushed back on this, pointing out that if a user just wants to delete history, silently also blocking the site (removing it entirely from Top Sites without saying so) gives them unexpected behavior.

The problem with the fix is that the dialog asks to the user if they want to remove from history, but then the code proceed also blocking the site, that is not told to the user and may be unexpected.
If the user wanted to effectively just remove history, not block the site, they will get the wrong behavior.

I'm not expert of this code, but it looks like the proposed solution is broad and may cause unexpected behavior, actually removing control from the user rather than increasing it.

It's touching the right problem though, someone should eval a UX solution.

I got a second feedback from another reviewer thecount (a mozilla engineer) and he was the one who led me to the right fix for the bug.

If you log link.url and searchProvider.url, like this console.log(link.url, searchProvider.url);

Right before this line: https://searchfox.org/firefox-main/source/toolkit/modules/NewTabUtils.sys.mjs#1093

And then on startup, I see this in the logs: "https://www.amazon.com/ https://amazon.com".

So this is the line that causes the url to be changed, and now the url is no longer removable because it no longer matches the original places url.
one solution might be to store "originalUrl" link.originalUrl = link.url in the block I linked above, and then when we delete the url, check if we have "originalUrl" and use that instead"? So something like link.originalUrl || link.url.

With this feedback, I was able to finally understand the bug.

Issue

// toolkit/modules/NewTabUtils.sys.mjs

links.forEach(link => {
       let searchProvider = getSearchProvider(NewTabUtils.shortURL(link));
        if (searchProvider) {
          link.url = searchProvider.url; // <= swap is done here
        }
      });

The issue was from here: you see Firefox does a check to see if amazon.com is already stored as a search-shortcut provider and then it quietly drops the url and replaces it with the internal searchProvider.url. This is why when we click "Delete History" nothing happens because we have lost the url that was supposed to match what we have in Places (a database in Firefox).

What is a search-shortcut provider, It means "a site Firefox knows how to search directly", and Amazon qualifies because Amazon has its own product search.

What this means

Before a tile ever reaches the New Tab page, Firefox checks each link against its built-in list of search-shortcut sites (Google, Amazon, Bing, DuckDuckGo, eBay, Twitter, Wikipedia). If the link matches one of these, Firefox swaps that tile's url to a version meant to trigger a search on that site, not to visit the homepage you actually browsed to.

Understanding the Bug (Part B)

Mental model

The mental model to have in Firefox is

Frontend: the New Tab Page (React), shows the tiles, builds the request
The request itself: the payload sent from frontend to backend
Backend: PlacesFeed.sys.mjs, receives the request, touches the actual database (your browsing history)

Like when building a To-do App, when you click on an item to delete from the database, you send the id of the item as a payload to the backend (either in the URL or Request Body). But here, the real id (original_url) was quietly being generated and never forwarded, the frontend only ever knew about url, which by that point pointed to the wrong thing.

So, for the fix we are going to be borrowing heavily from the full-stack MVC architecture

Breaking down the fix

We make sure that we do not lose reference to the url before it gets silently swapped out by Firefox, so we do something like this link.original_url = link.url; here, we are storing away the url in a variable called original_url and it will be referenced later when we want to delete a site.

Allow me to break down the fix using REST API from Nodejs.

A This is like a backend endpoint that serves your frontend a list which we use to create the Tiles. Here is where we create the Top Sites and send to the frontend, but we quietly rename a field along the way.

app.get("/topsites", (req, res) => {
  const items = getLinksFromDatabase();

  const response = items.map(item => {
    const searchProvider = getSearchProvider(item);
    if (searchProvider) {
      return {
        ...item,
        original_url: item.url,      // <=backup the real id/url
        url: searchProvider.url,     // <=overwrite what the frontend will see
      };
    }
    return item;
  });

  res.json(response);
});

B A user clicks a button which fires off a delete request and then we send both the url and original_url to the backend server.

fetch("/api/delete-history", {
  method: "DELETE",
  body: JSON.stringify({
    url: site.url,
    original_url: site.original_url,
  }),
});

C The backend receives the request and decides what to actually delete

app.delete("/api/delete-history", (req, res) => {
  const { url, original_url } = req.body;
  db.deleteEntry(original_url || url);
  res.sendStatus(200);
});

It checks: "do I have an original_url? If yes, use that to delete. If not, fall back to url."

This is important, because if it only used url, it would try to delete the search provider's link instead of the real saved site, and the deletion would silently fail or delete the wrong thing.

The Fix

Finally !!!!, now that we have a solid understanding of the issue and the fix, let us go ahead and implement.

A. Equivalent to Step 1 from the Rest API

// toolkit/modules/NewTabUtils.sys.mjs
links.forEach(link => {
  let searchProvider = getSearchProvider(NewTabUtils.shortURL(link));
  if (searchProvider) {
    link.original_url = link.url;
    link.url = searchProvider.url;
  }
});

B. Equivalent to Step 2 from the Rest API

// browser/extensions/newtab/content-src/lib/link-menu-options.mjs
action: {
  data: {
    onConfirm: [
      ac.AlsoToMain({
        type: at.DELETE_HISTORY_URL,
        data: {
          url: site.url,
          pocket_id: site.pocket_id,
          forceBlock: site.bookmarkGuid,
          original_url: site.original_url,
        },
      }),
    ],
  },
},

C. Equivalent to Step 3 from the Rest API

// browser/extensions/newtab/lib/PlacesFeed.sys.mjs
case at.DELETE_HISTORY_URL: {
  const { url, forceBlock, pocket_id, original_url } = action.data;
  lazy.NewTabUtils.activityStreamLinks.deleteHistoryEntry(
    original_url || url
  );
  break;
}

Conclusion

I waited for my patch to be approved and landed.

TLDR:

The issue was that Amazon was in the user's actual history, but the displayed url got silently swapped to the search-shortcut version, so the delete call looked for a url that no longer existed in Places.

Links:

🕷️ BUG: https://bugzilla.mozilla.org/show_bug.cgi?id=1628669

💗 PATCH: https://phabricator.services.mozilla.com/D292910

👤 MY PROFILE ON BUGZILLA: https://bugzilla.mozilla.org/user_profile?user_id=786766

Thank you, please follow me

Ask me anything (RAG)

Ifeanyi Chima — Sat, 25 Jul 2026 16:15:19 +0000

This is a submission for the Gemma 4 Challenge: Build with Gemma 4

What I Built

At LASU, students constantly ask each other things like "is this lecturer strict," "is this hostel safe," "what's SIWES actually like at this company," but that knowledge lives scattered across WhatsApp groups, Twitter threads, and word of mouth. It gets lost the moment a graduating class leaves. AMA was built to solve that: a shared memory for the school, where real student experiences get collected once and stay searchable by anyone, forever, instead of vanishing into a thousand disconnected chats.

Demo

Code

GitHub: https://github.com/MasterIfeanyi/hackathon-today

How I used Gemma 4

We used Gemma 4 (via OpenRouter) as the answer-generation model, and built the project around Retrieval-Augmented Generation (RAG), not fine-tuning, since we needed the answers to update instantly as new stories get submitted, without retraining anything.

The pipeline works like this: when a student submits a story or review, we generate an embedding for it using Google's Gemini embedding model and store both the text and the embedding in MongoDB Atlas, using MongoDB Vector Search as our vector database. When someone asks a question, we embed the question the same way, run a vector similarity search to pull the most relevant stories, and pass only those into Gemma 4 as context, so every answer is grounded in real submissions instead of the model guessing.

On the frontend, we used Next.js (App Router), Tailwind CSS v4 for styling, Zustand for lightweight UI state, and TanStack React Query for handling data fetching and caching.

Hackathon

This was done as part of a university hackathon hosted by Google.

Thank you, please follow me

Fullscreen icon RTL language support in Firefox browser

Ifeanyi Chima — Tue, 14 Jul 2026 11:34:31 +0000

This is a submission for DEV's Summer Bug Smash: Smash Stories powered by Sentry.

Our target is to make sure that when the firefox browser is set to RTL mode the fullscreen icon flips as well to follow suite.

Introduction

When Firefox is set to an RTL (right-to-left) language like Arabic, the fullscreen icon inside the zoom sidebar still looks like it's designed for LTR (left-to-right) languages. It should be mirrored/flipped to match RTL direction.

What's RTL?

Languages like Arabic and Hebrew read from right to left. Browsers have a concept called dir="rtl" that flips the layout. Icons that have a "direction" to them (like arrows, expand icons) should also flip to feel natural.

The plan:

First, let's find where the zoom sidebar and its fullscreen icon live in the Firefox codebase
See how the icon is currently being used
Figure out how to make it flip for RTL

You can set your firefox browser to read from right-to-left using this in the console CTRL+SHIFT+ALT+I

document.documentElement.setAttribute("dir", "rtl")

1. Find the files:

Zoom sidebar HTML file

We can start by searching Searchfox (Mozilla's online code search) for terms like "zoom sidebar fullscreen" and "appmenu zoom controls." That search led me to appmenu-viewcache.inc.xhtml, and inside it I saw this markup:

<toolbaritem id="appMenu-zoom-controls" class="subviewbutton toolbaritem-combined-buttons" closemenu="none">
  <label class="toolbarbutton-text" data-l10n-id="appmenuitem-zoom"/>
  ...
  <toolbarbutton id="appMenu-fullscreen-button2"
                       class="subviewbutton subviewbutton-iconic"
                       data-l10n-id="appmenuitem-fullscreen"
                       type="checkbox"
                       tooltip="dynamic-shortcut-tooltip">
           <observes element="View:FullScreen" attribute="checked"/>
        </toolbarbutton>
</toolbaritem>

FLUENT: Firefox uses the fluent localization system (more in later articles)

appmenuitem-zoom is the localization label for the word "Zoom" that sits above the row of buttons (-, 100%, +, fullscreen). It's a distinctive, low-noise string and searching for it locally in VS code is a good way to land on the exact zoom row markup without pulling in unrelated matches.

Let's start by searching for the zoom sidebar files using this grep syntax:

grep -rn "appmenuitem-zoom" browser/base/content/

What we found:

The fullscreen icon lives inside the zoom row of the hamburger menu (☰). In the HTML file at browser/base/content/appmenu-viewcache.inc.xhtml, the button is:

<toolbarbutton id="appMenu-fullscreen-button2"
                       class="subviewbutton subviewbutton-iconic"
                       data-l10n-id="appmenuitem-fullscreen"
                       type="checkbox"
                       tooltip="dynamic-shortcut-tooltip">
           <observes element="View:FullScreen" attribute="checked"/>
        </toolbarbutton>

The ID of the fullscreen button in the zoom row of the hamburger menu is appMenu-fullscreen-button2.

This is very important to keep in mind.

Zoom sidebar CSS file

Let us find the CSS file where its icon is defined using this grep syntax

grep -rn "appMenu-fullscreen-button2" browser/themes/

What we found:

This finds browser/themes/shared/menupanel.css, the file where the fullscreen icon's image is actually set, which is where we will make our fix.

The fullscreen icon

grep -rn "fullscreen.svg" browser/themes/shared/

We can see that there is an image fullscreen.svg that serves as the icon, located at browser/themes/shared/icons/fullscreen.svg and gets applied via browser/themes/shared/menupanel.css

Here, we see the fullscreen icon, which looks like pointing outward from a center.

Left-to-right

Right-to-left

2. Figuring out how to make it flip

We need to take note of two things that will guide us to the actual fix.

From what we saw here, we know that the zoom icon could live inside of toolbarbutton

<toolbarbutton id="appMenu-fullscreen-button2"
                       class="subviewbutton subviewbutton-iconic"
                       data-l10n-id="appmenuitem-fullscreen"
                       type="checkbox"
                       tooltip="dynamic-shortcut-tooltip">
           <observes element="View:FullScreen" attribute="checked"/>
        </toolbarbutton>

According to Mozilla guidelines,

<toolbarbutton> is a Firefox custom element (defined in toolkit code, not in this XHTML file), and it generates its own internal "anonymous content" at runtime; meaning the <image class="toolbarbutton-icon"> and <label class="toolbarbutton-text"> children are injected by the custom element's own implementation at render time.

We can confirm the actual DOM structure using

document.getElementById("appMenu-fullscreen-button2").outerHTML

This returns

<toolbarbutton xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" id="appMenu-fullscreen-button2" class="subviewbutton subviewbutton-iconic" data-l10n-id="appmenuitem-fullscreen" type="checkbox" tooltip="dynamic-shortcut-tooltip" label="Full screen">
  <observes element="View:FullScreen" attribute="checked"/>
  <image class="toolbarbutton-icon" type="checkbox" label="Full screen"/>
  <label class="toolbarbutton-text" crop="end" flex="1" value="Full screen"/>
</toolbarbutton>

Now, we know <toolbarbutton> elements in Firefox's UI don't render the icon directly on themselves; they render it inside a child element with the class .toolbarbutton-icon

We can confirm this once again by inspecting the element in the Browser Toolbox, when we run

document.getElementById("appMenu-fullscreen-button2").querySelector(".toolbarbutton-icon")

it returned:

<image class="toolbarbutton-icon" type="checkbox" label="Full screen">

This confirms that's where the icon or image actually lives and we can target it using this:

#appMenu-fullscreen-button2 > .toolbarbutton-icon

This leads us to the next step in finding the fix.

According to Mozilla guidelines,

icons implying direction should mirror in RTL, using this exact pattern as the recommended technique

.element-with-icon:dir(rtl) {
  transform: scaleX(-1); /** scale: -1 1; does the same horizontal flip **/
}

Now, we know what our fix should be

The Fix

The fix, then, is to add a CSS rule that uses :dir(rtl) to horizontally flip the fullscreen icon whenever Firefox is in RTL mode. Since the icon itself lives inside the .toolbarbutton-icon child element, that's the element we need to target, using scale: -1 1 to perform the flip.

The file to edit is: browser/themes/shared/menupanel.css

/* To flip an icon for RTL using scale: */
#appMenu-fullscreen-button2:dir(rtl) > .toolbarbutton-icon {
  scale: -1 1;
}

This means "when this specific button is inside an RTL context, flip its icon child horizontally."

Summary

When you open the hamburger menu (☰) in Firefox, there's a zoom row that looks like: Zoom — [-] 100% [+] [⤢]. That last icon [⤢] is the fullscreen button (appMenu-fullscreen-button2).

In Arabic and other RTL languages, this icon doesn't flip to match the reading direction, it stays the same as in English (LTR). It should be mirrored.

💗 PATCH: https://phabricator.services.mozilla.com/D309258

🕷️ BUG: https://bugzilla.mozilla.org/show_bug.cgi?id=2029514

👤 MY PROFILE ON BUGZILLA: https://bugzilla.mozilla.org/user_profile?user_id=786766

Writing unit test for Firefox private browsing window

Ifeanyi Chima — Sun, 05 Jul 2026 17:35:35 +0000

Our indicator looks like this: an icon + a label.

The browser has an indicator for when a user is in private mode. The indicator lives in two places under different instances:

The first instance is when the user is in "Horizontal Tabs" when the browser tabs are in the TabsToolbar (tab-bar or toolbar). So, the indicator shows both the icon and it's label.
The second instance is when the user has "Vertical Tabs" turned on. So, the indicator moves or shows up in the Navbar (which contains extensions, address bar) and this time only the icon shows up, no label.

Our task is to write a unit test to confirm that the icon shows up in both instance.

We start off by running this search grep -r "private-browsing-indicator-with-label" --include="*.xhtml" --include="*.js" --include="*.css" .

We found two things.

The "Shared" CSS file that controls the visibility of this icon browser/themes/shared/browser-shared.css
The browser/base/content/private-browsing-indicator.inc.xhtml — this is where the indicator's actual markup (HTML-like structure) lives.

Now, we can check the CSS file for where it controls the visibility of the indicator by using this syntax grep -n -A 10 "private-browsing-indicator-with-label" browser/themes/shared/browser-shared.css

What we find out in the file:

.private-browsing-indicator-with-label {
  :root:not([privatebrowsingmode="temporary"]) &,
  #navigator-toolbox:not([tabs-hidden]) #nav-bar > & {
    display: none;
  }
  #navigator-toolbox[tabs-hidden] #nav-bar > & {
    margin-inline-end: var(--space-medium);
    > .private-browsing-indicator-label {
      display: none;
    }
  }
}

What this means:

When the window isn't a private window (we are in normal mode) - it will hide the indicator completely.
When we have horizontal tabs in private window, hide the indicator from the navbar (which contains extensions, address bar) and then the indicator will move to the TabsToolbar (which actually contains browser tabs).

The image above shows that we are still in horizontal tabs

When we have vertical tabs while still in private window, the private-browsing-indicator will move to the navbar and then hide the label part of the indicator and keep only the icon.

The above image shows vertical tabs enabled

Writing the tests

Before we begin writing the tests, we would need to find other existing tests in the codebase to take inspiration from them, by using the search query:

grep -n "is_visible\|isVisible\|is_hidden\|isHidden" testing/mochitest/BrowserTestUtils/BrowserTestUtils.sys.mjs and then we read the file sed -n '325,350p' testing/mochitest/BrowserTestUtils/BrowserTestUtils.sys.mjs

This gives us a lot of information:

What to check: both copies of .private-browsing-indicator-with-label (one inside TabsToolbar, one inside nav-bar)
How to toggle vertical tabs: by using the pref sidebar.verticalTabs as seen here

SpecialPowers.pushPrefEnv({ set: [["sidebar.revamp", true], ["sidebar.verticalTabs", true]] })

Task structure: add_task(async function () {...})
Check visibility: BrowserTestUtils.isVisible(element)
How to open a private window (modern style): BrowserTestUtils.openNewBrowserWindow({ private: true })

Now, we can write the tests as follows:


/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

"use strict";

// The private browsing indicator lives in two possible spots:
// - Inside #TabsToolbar (shown with icon + label, for horizontal tabs)
// - Inside #nav-bar (shown with icon only, for vertical tabs)
// This test makes sure at least one copy is always visible in a
// private window, no matter which tabs layout is active.

add_task(async function test_indicator_horizontal_tabs() {
  const win = await BrowserTestUtils.openNewBrowserWindow({ private: true });

  let tabsToolbarIndicator = win.document.querySelector(
    "#TabsToolbar .private-browsing-indicator-with-label"
  );
  let navBarIndicator = win.document.querySelector(
    "#nav-bar .private-browsing-indicator-with-label"
  );

  ok(
    BrowserTestUtils.isVisible(tabsToolbarIndicator),
    "Indicator should be visible in TabsToolbar with horizontal tabs"
  );
  ok(
    BrowserTestUtils.isHidden(navBarIndicator),
    "Indicator in nav-bar should be hidden with horizontal tabs"
  );

  await BrowserTestUtils.closeWindow(win);
});

add_task(async function test_indicator_vertical_tabs() {
  await SpecialPowers.pushPrefEnv({
    set: [
      ["sidebar.revamp", true],
      ["sidebar.verticalTabs", true],
    ],
  });

  const win = await BrowserTestUtils.openNewBrowserWindow({ private: true });

  let tabsToolbarIndicator = win.document.querySelector(
    "#TabsToolbar .private-browsing-indicator-with-label"
  );
  let navBarIndicator = win.document.querySelector(
    "#nav-bar .private-browsing-indicator-with-label"
  );

  ok(
    BrowserTestUtils.isHidden(tabsToolbarIndicator),
    "Indicator in TabsToolbar should be hidden with vertical tabs"
  );
  ok(
    BrowserTestUtils.isVisible(navBarIndicator),
    "Indicator should be visible in nav-bar with vertical tabs"
  );

  await BrowserTestUtils.closeWindow(win);
  await SpecialPowers.popPrefEnv();
});

add_task(async function test_indicator_not_shown_in_normal_window() {
  const win = await BrowserTestUtils.openNewBrowserWindow();

  let indicators = win.document.querySelectorAll(
    ".private-browsing-indicator-with-label"
  );

  for (let indicator of indicators) {
    ok(
      BrowserTestUtils.isHidden(indicator),
      "Indicator should never be visible in a normal (non-private) window"
    );
  }

  await BrowserTestUtils.closeWindow(win);
});

Explaining the test:

Now, here is what this test is doing. Remember at the beginning, I said our private browsing lives in two possible spots:

Inside #TabsToolbar (shown with icon + label, for horizontal tabs): This is when we have private browsing enabled, but we are still using horizontal browser tabs (the default)
Inside #nav-bar (shown with icon only, for vertical tabs): This is when the user has enabled / turned on Vertical browser tabs.

Test 1: Horizontal Browser Tabs

The first test is saying open a private browser window using await BrowserTestUtils.openNewBrowserWindow({ private: true }); and then we are making sure that when we are in Horizontal Mode - the navbar indicator IS NOT showing. The only indicator that should be showing in Horizontal Mode is the tabsToolbarIndicator

Test 2: Vertical Browser Tabs

We open a private browser window using await BrowserTestUtils.openNewBrowserWindow({ private: true }); and now, we assume that the user has turned on vertical tabs, how do we do that in our test ?.... by using this pref to turn on vertical tabs during the test run

await SpecialPowers.pushPrefEnv({
    set: [
      ["sidebar.revamp", true],
      ["sidebar.verticalTabs", true],
    ],
  });

Now, in Vertical Mode the only indicator that should show is the navBarIndicator and the other one should not show. Also, do not forget to close the browser window and cleanup the Pref using

await BrowserTestUtils.closeWindow(win);
await SpecialPowers.popPrefEnv();

Test 3: Normal Browser Window

In this test, we open a normal browsing window and we make sure that none of those labels either navBarIndicator or tabsToolbarIndicator show up when the user is NOT using private browsing.

TLDR:

What each test does, briefly

test_indicator_horizontal_tabs: opens a private window in normal (default) tabs mode, checks the TabsToolbar indicator is visible and the nav-bar indicator is hidden.
test_indicator_vertical_tabs: opens a private window, turns on vertical tabs mode, check that the nav-bar indicator is visible, TabsToolbar indicator hidden.
test_indicator_not_shown_in_normal_window: opens a completely normal (non-private window) and makes sure neither indicator shows up at all since this isn't a private window in the first place.

Registering the test

In Firefox, whenever you write a test, you must register the test in browser.toml which is meant for that particular component - We are writing a test for the private browsing component; hence the file is located at browser/components/privatebrowsing/test/browser/browser.toml

Components are registered in an alphabetical order in this file.

["browser_privatebrowsing_favicon.js"]

["browser_privatebrowsing_history_shift_click.js"]

["browser_privatebrowsing_indicator.js"] # our unit test 

["browser_privatebrowsing_last_private_browsing_context_exited.js"]

["browser_privatebrowsing_lastpbcontextexited.js"]

["browser_privatebrowsing_localStorage.js"]

SUMMARY:

When a user switches Firefox to private browsing mode, the indicator shows up, and the bug report was that there was never a unit test to ensure that the indicator is present in various browsing modes and so we wrote unit tests for those instances of the browser mode

Horizontal tabs mode (while private browsing is turned on)
Vertical tabs mode (while private browsing is turned on)
Normal browsing mode.

Find the Patch Here: https://phabricator.services.mozilla.com/D310523

Find the Bug Here: https://bugzilla.mozilla.org/show_bug.cgi?id=1927615

THANK YOU

[Boost]

Ifeanyi Chima — Mon, 29 Jun 2026 08:29:49 +0000

Weekly community-sourced tech resources

Hemapriya Kanagala for The DEVengers

Jun 26

Dev Opportunity Radar #5: A Fully Funded Trip to AWS re:Invent, Google Cloud Career Launchpad, and a $1,000 Award

#discuss #community #opportunities #resources

9 min read

[Boost]

Ifeanyi Chima — Tue, 23 Jun 2026 13:37:49 +0000

KristinZ

Jun 8

From React Developer to AI Engineer: What Actually Changes

#typescript #ai #webdev #career

6 min read

Solstice cipher: Turing complete

Ifeanyi Chima — Mon, 08 Jun 2026 20:49:21 +0000

This is a submission for the June Solstice Game Jam

What I Built

Solstice Cipher is a browser-based game built around the tension between light and darkness — the core theme of the June Solstice.

The screen is split into two halves: pitch black on the left, golden yellow on the right. A Caesar cipher is presented to the player in a floating modal. Decode it correctly and the light grows. Guess wrong and the darkness creeps forward.

The game ends when either side fully consumes the screen. Darkness wins by default if you keep getting answers wrong.

The cipher words are selected randomly from a pool of over 6,500 common English words and encrypted using Caesar cipher with a shift of 3. Google's Gemma 4 model handles the encryption of each word on the server, with a verified fallback to ensure the player always gets a mathematically correct puzzle.

Video Demo

Code

MasterIfeanyi / solstice-game

This is a Next.js project bootstrapped with create-next-app.

Getting Started

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.js. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.

Learn More

To learn more about Next.js, take a look at the following resources:

Next.js Documentation - learn about Next.js features and API.
Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more…

View on GitHub

How I Built It

The stack is Next.js 16 with JavaScript, plain CSS modules, and Tailwind v4.

The architecture is built around a single GameContext using React's Context API, which broadcasts game state to every component without prop drilling. localStorage persists the light and dark widths across page refreshes so your progress survives an accidental reload.

The word selection pipeline works like this: a random word is picked on the server from a curated list of 6,500+ words sourced from Google's open source 10,000 most common English words list. That word is sent to Gemma 4 via OpenRouter to encrypt using Caesar cipher shift 3. Our server then verifies Gemma's encryption independently and corrects it silently if there is a mismatch, so the player always gets a valid puzzle.

For true randomness, a unique seed and offset generated with Math.floor(Math.random() * 1000000) is passed with every request. A rate limit fallback handles OpenRouter 429 responses gracefully by falling back to local encryption, and a network failure fallback handles complete internet loss.

Key architecture decisions:

DRY principle applied throughout with reusable Button, Modal, Header, and Navbar components.
A storage.js utility abstracts all localStorage operations with SSR safety guards.
Caesar cipher logic lives in one encryptCaesar function used everywhere on the server.
useRef tracks recently used words to prevent Gemma from repeating itself without triggering re-renders.

Prize Category

Best Ode to Alan Turing

As a computer science grad myself, I look up to Turing. His work in cryptography inspired this mini-game. I am in awe of his ability to turn a problem of decrypting German messages into a mathematical problem and then how he built a physical machine that took his instructions and was able to decrypt German signals.

That same spirit lives in Solstice Cipher. The Caesar cipher is one of the oldest encryption algorithms in history, and this game puts the player in the position Turing's team faced at Bletchley Park: staring at encrypted text and racing to decode it.

Best Google AI Usage

Google's Gemma 4 model powers the encryption engine of every round via OpenRouter. Each word selected for the player is sent to Gemma 4 with a structured prompt instructing it to apply Caesar cipher shift 3 and return a verified JSON response. The server independently verifies Gemma's output and corrects any mismatch, ensuring the AI is genuinely doing cryptographic work on every single round rather than acting as a simple random number generator.

Copilot with an Eagle eye

Ifeanyi Chima — Mon, 25 May 2026 19:31:49 +0000

This is a submission for the GitHub Finish-Up-A-Thon Challenge

What I Built

In Nigeria today, insecurity and corruption is a very big issue with no hope in sight of solving it as they both go in tandem. I have been in multiple situations where I wished I could contact emergency services as soon as possible but to no avail. Also, to be honest when I started this project in 2025, the goal was to provide a very simple way to combat corruption by turning even the layman into a watchful vigilante. So, the goal of this project was to prototype a simple system called "Eagle Eye" that will allow you to make reports to the appropriate authorities about corruption and any insecurity in an area.

I really hope to make this platform or website actually grow into a nationwide tool complete with an admin dashboard and a response team. I took massive inspiration from the London underground railway system: "see something, say something".

Demo

Live link: https://ifeanyi-eagle-eye.netlify.app/home

GitHub Repo: https://github.com/MasterIfeanyi/Eagle-Eye-App

The Comeback Story

The project was previously using Firebase before and I racked up a bill of $180 which hurt massively, so I decided to re-write it using Nextjs and MongoDB, and my assistant of choice was GitHub Co-pilot. I chose Nextjs and MongoDB because Nextjs to me feels like a full-stack option with a built-in /api folder and MongoDB Atlas is a free database service that I could use to store reports and perform authentication of users. Along the way I decided to add a page where you could get phone number of emergency services. If not for this hack-a-thon, I may have never come back to this project because I have been putting it off for some time as I am was busy.

My Experience with GitHub Copilot

Building Eagle Eye was not a smooth process. There were moments where the project felt completely stuck, and honestly, GitHub Copilot was a massive part of that process, as I primarily write Nextjs, but Co-pilot guided me and took away my fears. GitHub Copilot helped me think through the architecture from the ground up, guiding decisions like how to structure the Next.js app directory, how to handle authentication with JWT and cookies, and how to connect the frontend to MongoDB. When I hit bugs, like a broken scroll on the hotlines page, a sticky header that refused to stick, or a location detector pulling the wrong city, GitHub Copilot did not just hand me answers. It explained why things were breaking so I actually understood the fix. What I appreciate most is that GitHub Copilot treated me like a developer who was learning, not one who needed things done for them. This project genuinely would not exist in its current state without that support. Although, I was limited to the Claude Haiku 4.5 model (free plan), I feel like it was sufficient enought to help me.

How to use Google Gemma 4 model

Ifeanyi Chima — Thu, 14 May 2026 08:58:30 +0000

This is a submission for the Gemma 4 Challenge: Write About Gemma 4

I Built a Celebrity AI Chat App with Google Gemma 4 26B-A4B, Here's Everything You Need to Know

I've always been fascinated by the idea of talking to your Elon Musk, but for now we would have to settle down for a chatbot that actually feels like them. So when Google dropped Gemma 4 in April 2026, I saw my chance. I built a web app with a chat UI where you pick a celebrity, and Gemma 4 slips into their persona and holds a full conversation with you. The results were genuinely impressive and sometimes hilarious.

But before I walk you through how I built it, let me give you a proper introduction to the models that made it possible.

1. Understanding the Google Gemma 4 Model Family

Gemma 4 is Google DeepMind's latest generation of open models, released on April 2, 2026. It comes in four distinct sizes, each targeting a different use case, from running on your phone to powering a server-grade workstation. All four models are multimodal (they can process text and images), licensed under Apache 2.0, and support over 140 languages.

Quick Comparison Table

Model	Architecture	Context	Audio	Best For
E2B	Efficient Dense	128K	✅	Mobile / Edge
E4B	Efficient Dense	128K	✅	On-device assistants
26B A4B	Mixture of Experts	256K	❌	High-throughput APIs
31B	Dense	256K	❌	Maximum quality

2. How to Get an API Key

Before you can start building anything with Gemma 4, you need API access. The good news? You have a couple of options and one of them is completely free to start.

Option A: Google AI Studio (Direct from Google)

Google provides direct API access to Gemma 4 through Google AI Studio. Here's how to get your key:

Go to aistudio.google.com
Sign in with your Google account
Click "Get API key" in the left sidebar
Click "Create API key"
Copy your key and store it somewhere safe (you won't be able to see it again)

That's it. Google AI Studio gives you a generous free tier to experiment with before you need to think about billing.

Never hardcode your API key in your frontend code. Always store it in an environment variable (.env file) and access it from your backend.

Add .env to your .gitignore before your first commit, not after.

Option B: OpenRouter

OpenRouter is a unified API gateway that gives you access to hundreds of models including all Gemma 4 variants through a single, OpenAI-compatible endpoint. That means you can switch models with one line of code change, get automatic fallbacks if a provider goes down, and even access the free tier of Gemma 4 31B without spending a cent to start.

To get your OpenRouter API key:

Go to openrouter.ai
Click "Sign In" and create an account
Once logged in, click "Get API Key" button from your dashboard
Click "New Key", give it a name (e.g. celeb-chat-dev), and hit create
Copy and save your key it starts with sk-or-...

You can optionally add credits to your account for paid usage, but to start experimenting, the free-tier models (including google/gemma-4-26b-a4b-it:free) are more than enough.

3. How to Use Google Gemma 4 Through OpenRouter

Alright, this is where the fun begins. Let me walk you through exactly how I wired up Gemma 4 via OpenRouter to power my celebrity chat app, from the first API call all the way to a working chat UI.

The Base URL and Model IDs

OpenRouter exposes Gemma 4 through a single endpoint that's fully compatible with the OpenAI Chat API format. If you've ever called GPT-4 or any other model via OpenAI's SDK, this will feel immediately familiar, you're literally changing one URL and one model string.

The base URL is:

https://openrouter.ai/api/v1/chat/completions

And the Gemma 4 model IDs on OpenRouter are:

Model	Model ID	Free Tier?
Gemma 4 E2B	`google/gemma-4-e2b-it`	✅
Gemma 4 E4B	`google/gemma-4-e4b-it`	✅
Gemma 4 26B A4B	`google/gemma-4-26b-a4b-it`	✅ (`:free` suffix)
Gemma 4 31B	`google/gemma-4-31b-it`	✅ (`:free` suffix)

To use the free tier of the 26B model for example, use google/gemma-4-26b-a4b-it:free as the model string.

Switching Models Without Rewriting Your Code

This is the quiet superpower of going through OpenRouter. Because the API schema is identical across all models, switching from the free 31B to the 26B MoE (which is faster and cheaper in production) is literally one line:

// During development
model: "google/gemma-4-31b-it:free"

// In production (faster, cheaper MoE)
model: "google/gemma-4-26b-a4b-it:free"

No refactoring. No new SDK. Just change the string. This is why I recommend OpenRouter for any serious project, you can prototype on free-tier models and graduate to the right production model without touching your integration code.

Your First API Call

Let's start simple with a raw fetch call in JavaScript, no SDKs needed:

const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.OPENROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "google/gemma-4-26b-a4b-it:free",
    messages: [
      { role: "user", content: "What's the capital of Nigeria?" }
    ],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

That's it. Three things to note:

Your API key goes in the Authorization header as a Bearer token
The response shape mirrors OpenAI, your answer lives at data.choices[0].message.content
You're billed (or rate-limited on free tier) per token, so max_tokens is worth setting explicitly

I was getting this error

google/gemma-4-26b-a4b-it:free is temporarily rate-limited upstream.

The free tier of Gemma 4 on OpenRouter is being hammered by too many users right now and Google AI Studio is throttling it. When you use the free tier on OpenRouter (google/gemma-4-26b-a4b-it:free), you are sharing a pool of rate limits with every other developer in the world using that same free model. So when too many people hit it at once, Google throttles it and you get that 429 error. But you already have a Google AI Studio API key sitting in your .env.local doing nothing right now. OpenRouter lets you connect your own Google AI Studio key so that your requests go through your personal quota instead of the shared free pool.

You have two options:

Option 1 — Add your Google AI Studio key to OpenRouter

Option 2 — Add retry logic to your API route

I went with Option 1 which is adding my Google AI Studio key to OpenRouter integrations

Go to: openrouter.ai/settings/integrations

Find Google AI Studio
Paste your Google AI Studio API key there

This gives you your own dedicated rate limit instead of sharing the free pool with everyone

The System Prompt; The Secret Weapon for My Project

Here's where Gemma 4 genuinely impressed me. Gemma 4 officially supports the system role natively; a big deal for an open model, since earlier generations required hacky workarounds. However, in my actual project I used a slightly different pattern that I found worked even better for persona-heavy apps: the user/assistant injection pattern.

Instead of passing the persona as a system message, I injected it as the first user message and followed it with a primed assistant response where the model explicitly "agrees" to become the character before the real conversation even starts:

const formattedMessages = [
  {
    role: "user",
    content: systemPrompt, // persona instructions injected here
  },
  {
    role: "assistant",
    // the model "confirms" the persona before the conversation begins
    content: `Understood. I am ${personName}. I will only speak about my own life, work, and experiences. Ask me anything about who I am.`,
  },
  // then the real conversation history follows
  ...messages,
];

The subtle advantage of this approach over a plain system message: the model has explicitly agreed to the role as part of the conversation context. That in-context confirmation produces noticeably stronger character lock-in across long conversations. The model is far less likely to slip out of persona when it has already "committed" to it in an early assistant turn.

The results were honestly uncanny. The model held the persona across multiple turns, matched the celebrity's tone and vocabulary, and even pushed back on out-of-character questions in a way that felt natural. The 256K context window meant I could carry a long conversation without the model ever "forgetting" who it was supposed to be.

Enabling Reasoning Mode

One of Gemma 4's standout features is its configurable thinking mode, you can ask the model to reason through a problem before giving its final answer. OpenRouter exposes this through a reasoning parameter:

body: JSON.stringify({
  model: "google/gemma-4-26b-a4b-it",
  messages: messages,
  reasoning: { enabled: true }, // turn on chain-of-thought
}),

When enabled, the response includes a reasoning_details array showing the model's internal thought process before the final answer. I didn't use this for the celebrity chat (you don't want Morgan Freeman visibly deliberating), but it's incredibly useful for any app where you want to show why the model said something for example; tutoring apps, code explainers, or decision-support tools.

One tip from the OpenRouter docs: if you're building an agentic tool or integrating with something like Claude Code or Cline, turn reasoning off. It adds latency and those tools are optimized for fast back-and-forth, not deep deliberation.

Thanks for Reading !

My Buddy and I

Ifeanyi Chima — Wed, 13 May 2026 16:33:04 +0000

This is a submission for the Gemma 4 Challenge: Build with Gemma 4

What I Built

I chose this project because as a kid (since age: 17) I have always had this vivid dreams of speaking with Elon Musk, he is kind of like my Idol and I would cherish the opportunity to have a conversation with him, until that day comes, this is what we would manage. When I came across this hackathon to test the lates model built by Google (Gemma 4) it was a no-brainer for me. I want the opportunity to understand the memory and context management of this model. I decided not to limit it to Elon Musk and included as much celebrities as possible. I want to give my friends the opportunity to test and use it.

Buddy is a web application that lets you have real, in-character conversations with iconic public figures such as athletes, billionaires, historical leaders, artists, and innovators. You pick a person, and the AI steps into their shoes completely. It speaks the way they speak, stays grounded in their real life and career, and refuses to break character.

Although, with this project I am not solving a problem like climate change or malaria cure, The problem Buddy solves is simple. Most AI chatbots are general-purpose. You can ask them anything, and they will answer as a neutral assistant. That is useful, but it is not immersive. Buddy flips that entirely. The AI is not an assistant anymore, it is a person. Ask Lionel Messi about his childhood in Rosario. Ask Steve Jobs why he believed design was everything. You get answers that feel like a real conversation, not a Wikipedia summary read back to you.

The experience Buddy creates is curiosity without friction. It is the feeling of sitting across from someone remarkable and just... asking them things.

Demo

Link: https://ifeanyi-celeb-chat.netlify.app

Code

GitHub: https://github.com/MasterIfeanyi/google-gemma4-hackathon

How I used Gemma 4

Buddy runs on Gemma 4 26B, accessed via OpenRouter using the google/gemma-4-26b-a4b-it:free model.

The choice of Gemma 4 over the smaller variants came down to one core requirement; persona consistency. Keeping an AI locked inside a specific person's personality across a full multi-turn conversation is genuinely hard. The model needs to remember who it is, match the person's tone and vocabulary, deflect off-topic questions naturally without sounding robotic, and stay grounded in real publicly known facts all at the same time. The smaller E2B and E4B variants are impressive for their size, but they tend to drift out of character more easily under pressure, especially when a user deliberately tries to break the persona with trick questions or unrelated topics.

The 26B model holds the character much more firmly. When you ask Messi a question in Spanish, it does not just translate, it responds with the rhythm and warmth of how Messi actually speaks. When you push Steve Jobs on a topic he would find irrelevant, it redirects with the kind of sharp confidence Jobs was known for. That level of nuance needs a bigger model.

One specific technical challenge worth mentioning is Gemma 4 does not support a native system role in its message format. To get around this, Buddy injects the personality prompt as a user / assistant turn pair at the very start of every request, effectively tricking the model into treating the persona as established context before the real conversation begins. The 26B model responds to this pattern reliably and stays locked in. Smaller models were noticeably less consistent with the same approach.

What Gemma 4 ultimately unlocked for Buddy was believability. Because the model is large enough to hold complex persona context across many turns, we never had to simplify the experience to make it work. We did not have to limit conversation length, restrict the types of questions users could ask, or hardcode fallback responses. The model handled edge cases we never explicitly planned for. When a user asked Messi to speak Spanish, Gemma 4 switched languages naturally and stayed in character at the same time, responding with the warmth and rhythm of how Messi actually communicates, without any instruction from us to do so. When users tried to break the persona with off-topic questions, the model deflected in the voice of the person, not with a generic AI refusal. That level of emergent, in-character behaviour is what a smaller model cannot reliably give you and it is what makes Buddy feel like a conversation rather than a demo.