DEV Community: 365Talents

Things I learned picking up a new language as an adult

Florian Lackner — Tue, 21 Oct 2025 12:33:57 +0000

Since I came to France six months ago, I have made a lot of progress with the French language. What started as nearly incomprehensible stuttering are now full phrases with rich vocabulary and even one little joke here and there. I've made picking up French my personal project, and it brings a lot of joy in my life. Understanding people in more and more contexts is enriching and helps with the struggles every expat experiences being far from home.

I recently stumbled across a talk by Chris Lonsdale from nearly ten years ago, where he talks about his experience learning languages. I highly recommend watching it if you haven't already. It resonated so well with me that it inspired me to write this blog post. He claims anybody can be fluent in a new language in six months. It sounds crazy, but having tried that myself, I believe he is right.

In his presentation, Chris claims that there are five basic principles you can apply and seven simple actions you can perform to boost your language skills massively. I will repeat them here and add my own comments.

The five basic principles

1. Focus on language content that is relevant to you.

I agree with him here. I still have unpleasant memories of high school times were we were forced to study rather obscure books in French, which included weird vocabulary and uninteresting stories. It was hell. It is so much harder to remember irrelevant information than interesting information that it becomes quickly frustrating.

2. Use your new language as a tool to communicate.

I guess the key take-away here is to use a language. If you want to convey some meaning, at least in Europe, you can always fall back to English. This is even possible in France, contrary to popular belief.

But you shouldn't use this escape hatch. Using a language takes practice you'll never get if you're not training. All beginnings will be hard, but ultimately you will progress, and that's what counts. Every little piece of information you communicate is a major win and should be treated as such. Feeling insecure about your level in a language is only going to hold you back.

I did a thought experiment one day to deal with this insecurity: I put myself into the other person's position and imagined a situation where I was talking to a person barely able to speak German (my native language). No matter how badly the person speaks, I would never consider their effort anything less than exactly that: a nice effort. In my opinion, it's remarkable if foreigners know your language, be it only so little. I think that the vast majority of people think of it that way. So why was I even embarrassed in the first place?

3. When you first understand the message, you will unconsciously acquire the language.

NEVER LEARN GRAMMAR. EVER.

In serious terms, you should always focus on the message. The rest follows naturally. Learning grammar is the exact opposite. You focus on the language's syntax by trying to learn and apply logical rules. That's how a computer might try to approach learning a language, but for humans, this is a dead-end.

In fact, have you ever noticed how native speakers of any language do not know grammar rules while applying them correctly 100% of the time? The most extreme example is children. They have never heard of grammar but speak as error-free as their parents. When asking them why they use this or that grammatical construction, they cannot give a better answer than: "Because that's how it is."

I believe that our brain is naturally "optimized" to find and internalize these rules subconsciously. This way, we can apply them with lightning speed and astonishing correctness without even thinking about them.

4. Language learning is physiological training.

This might be new to many. Chris tells the story of a Taiwanese woman who excelled in English in school but utterly failed to understand English spoken by native speakers once confronted with it. The idea is that our ears, i.e., our brains, need to learn to hear foreign sounds.

My favorite example of this is the four types of "tch" sounds in the Bosnian-Croatian-Montenegrin-Serbian language. There are two pairs: č / ć and dž / đ. You can find more information (including hearing samples) here. It is nearly impossible to hear the differences for me, how about you?

The same argument also applies to speaking. It takes muscles to do, and different languages use different movements of these muscles. We can train these movements like athletes do in sports. I witnessed a massive improvement in my ability to say certain French words after a couple of months. Initially, it felt like my tongue was somehow tied to a knot when attempting them. This feeling vanishes more and more every day. And if I think about it in retrospect, it really is similar to the clumsy feeling when picking up a new sport. Or when taking first dance lessons.

5. Psycho-physiological state matters.

This is a no-brainer on the one hand, but on the other hand, it's easy to forget about. If your brain is busy with other things, you won't learn. Especially important is staying relaxed when you don't understand something. It's normal, and being angry about it is as pointless as it is hindering your learning efforts.

The seven actions

1. Listen a lot.

Obvious and still often overlooked. You can basically soak your mind in a language. I think it's not necessary to listen actively all the time. A radio in the background also helps. Your brain will get used to the language this way.

2. Focus on getting the meaning first.

I wholeheartedly agree. Sometimes, I catch myself obsessing over single words and their meaning. While thinking about it, I lose context and I stop understanding most of what is said.

Another aspect is body language. It is actually different in most countries and conveys so much meaning. This is especially visible in Italy, the capital of expressive body language, in my opinion, but it applies everywhere.

And one last thing: We can use things we already know. For example, French shares a lot of its vocabulary with English. I use this a lot to guess the meaning of new words in French, and it works way better than it should.

3. Start mixing.

The call to action here is to be creative. Try new combinations of words, try to invent new expressions, etc. Babies, my great role models in language learning, talk like this.

In my experience, the outcome conveys its meaning while also sounding funny to natives. So, you've basically cracked a joke in a foreign language; congratulations. In essence, whatever works is fine and should be used.

4. Focus on the core.

Chris presents some statistics here. He claims that:

1000 words cover 85% of what you say on a daily basis.

3000 words cover 95% of what you say on a daily basis.

If it is true, this is way less than I thought. Three thousand words does not sound impossible; quite the contrary. And if you can say 95% of what you want to say in your daily life one could argue that you speak the language.

A sub-advice he gives is to focus on your "toolbox" of words. This means phrases like "What is this?" ("Qu'est-ce que c'est ?" in French, believe it or not), "What does this mean?", etc. This gives an excellent foundation and enables you to communicate and learn much quicker because you don't need to leave the language to ask these questions — Big recommendation from me as well.

5. Get yourself a language parent.

Chris uses the word parent to hint that babies learn languages this way. One could also say a mentor. A mentor should be a person that is genuinely interested in you as a person and somebody who helps you to communicate. The goal is a safe environment where you can speak comfortably. He claims this concept is successful as it is used by billions of parents all over the world, and all of their kids are able to speak in the end — A convincing argument for me.

I totally agree with this one. I had several mentors throughout my French adventure, and it is the biggest boost for language learning, in my opinion. One of my mentors was a good French friend with whom I started speaking only in French from the day I moved there.

It was hard initially, but he did not get tired of helping me out when I was looking for words, and my proficiency in French increased noticeably every week. There are many ways to find these mentors: friends, online dating, sports clubs, work colleagues; you name it.

6. Copy the face.

This supposedly makes it easier to copy the native accent. I tried this once in high school to fake a British accent, and it really worked. I have yet to do more experiments, but it's an interesting idea I will pursue further.

7. Directly connect to mental images.

Don't translate from one language into another in your head. Connect the idea, the image, the feeling directly to the word in the new language, like it is connected to the word in your native language.

This is great advice and also one of the many mistakes made by schools over and over. Vocabulary lists are one negative example. They incentivize translating in your head, among other problems they have.

In my experience, it is a habit to translate in the head. The same is true for actively doing the exact opposite. I'm trying to make it a habit to connect the words directly to the ideas they represent, and I'm seeing two benefits:

The respective words started popping into my mind whenever I saw something or thought about an abstract idea.
I started to have a feeling about when which word is appropriate. Many words have very similar meanings, like walking and marching in English. Still, there is a difference; sometimes, you can't use one where you can use the other. I'm sure there is always an explanation / a rule for these cases, but that doesn't help when you're in the middle of saying a sentence. The feeling is instantaneous and almost always right, so go for it.

Conclusion

Chris' talk was eye-opening for me. It put into words better than I ever could many vague feelings I had about language learning in these past couple of months. Of all the tips he gave, I like the one with the mentor best. It has helped me a lot with French while also being very nice from a social perspective. If you take one of the ideas presented here home, make it this one.

Why do we need async/await in JavaScript?

Florian Lackner — Tue, 21 Oct 2025 12:32:19 +0000

First posted here.

Async/await is a major source of confusion in JavaScript. People tend just to add and remove the async and await keywords until the code works (or seems to work). In this article, I want to explain what async/await actually means by developing the concept from vanilla, synchronous JavaScript to asynchronous JavaScript with the async/await syntax sugar. It is my personal take on the subject. I hope some will find it interesting.

Disclaimer: I use Node.js as an example of a JavaScript runtime in this article. However, what's discussed also applies to other runtimes like web browser JS engines. All these environments follow similar architectures.

What problem does it solve?

Suppose you have a function that does some I/O.

function handleRequest() {
  try {
    const data = doDatabaseQuery();
    const fileName = doElasticsearchQuery(data);
    const result = readMyFile(fileName);
    return result;
  } catch (err) {
    return handleError(err);
  }
}

Here we assume that the query functions and the readMyFile function will block the JavaScript code while they perform their I/O. Eventually, it will be done, and we can continue where we left off. They will signal an error by throwing. We handle it with a try/catch block.

Doing database queries or other I/O like network requests or filesystem operations takes a very long time™ compared to running your JavaScript code. This is fine in this example if we look at a single request/response. But web servers usually handle thousands of requests. And then this model breaks. To understand why we have to look at how Node.js runs your JS code.

Node.js has a single-threaded event loop

Node.js runs all your JS code in a single thread. The exact reasoning behind this design choice is fascinating but out of scope for this article. In my opinion, the two most compelling arguments in favor of Node's architecture are:

The other option would be to use concurrent threads. This comes with many complexity hazards like synchronization, deadlocks, etc. In this sense, Node's model is simpler.
It turns out that I/O heavy applications like web servers tend to wait a lot. And by that, I mean a lot. They do nothing else, basically. The heavy lifting usually happens outside the web server, in a database, in elastic search, you name it. The web server just requests the data, waits for it, and glues it together to send it back to the client. So having several threads will not make your code more performant because its performance is not CPU-bound.

However, while JS code runs sequentially, we can still work on many requests simultaneously. For example, you can start your washing machine, dishwasher, and microwave one after another and then wait for them to finish their respective tasks. You can do the same with requests to your database, elastic search, etc.

The big question is: How can we wait without blocking?

Callbacks

So code running in Node is not supposed to stop executing to wait for something external to be done. But we often need to do something after say, a network request was completed. The way this is handled is straightforward: We give the runtime a function to call after it performed our I/O operation with its result. This function is called a callback function. We can see how the example would look like using callbacks.

function handleRequest() {
  doDatabaseQuery(function (err, data) {
    // first callback
    if (err) {
      handle(err);
      return;
    }

    doElasticsearchQuery(data, function (err, fileName) {
      // second callback
      if (err) {
        handleError(err);
        return;
      }

      readMyFile(fileName, function (err, result) {
        // third callback
        if (err) {
          handleError(err);
          return;
        }

        sendToClient(result); // strawman function to send a response to the client
      });
    });
  });
}

The I/O functions take a second argument this time, the callback. Note that we couldn't just return our result in this case. When handleRequest runs it will call doDatabaseQuery and then it will return immediately. The Node.js runtime will later call the callback, which will call doElasticsearchQuery. The callback also returns quickly. It will call only readMyFile with another callback which will finally call sendToClient to finish our request once the file was read. We returned result in the original example. This is impossible with callbacks, so we're using this strawman function sendToClient that sends the response back to the client.

Error handling is explicit in this model. By convention, the first argument of the callback function is an error object. If it is not undefined, something went wrong, and we can handle it in the callback. The second argument is, by convention, the result of the I/O operation. There are other styles, but they all boil down to the same idea: The error is communicated via some error argument to the callback.

This is the way Node.js handles I/O. Many will rightfully argue that the code looks messier than initially. The code tends to get more and more unreadable if the nesting of the callbacks becomes too deep. And error handling makes things even worse. This problem is referred to as callback hell. Several abstractions over callbacks have been developed to deal with this. The most widely used one is called Promise.

Promises

The idea of an asynchronous function not returning its result contributes greatly to the unreadability of callback-spaghetti-code. Promises fix this by letting an asynchronous function return something again. But because asynchronous functions still can't block, it can't be the actual value. Instead, they return a Promise, which can be interpreted as: "I promise that the value will eventually be here." The jargon is: "The promise resolves to the value". So this time, the I/O functions return promises that resolve to their respective values.

Furthermore, promises simplify error handling by splitting the error handling logic from the business logic. Instead of getting the error in the callback, you can register a dedicated error callback, which gets called instead of the normal callback if there is an error.

function handleRequest() {
  const dataPromise = doDatabaseQuery();
  dataPromise.catch(err => handleError(err));

  const fileNamePromise = dataPromise.then(function (data) {
    // first callback
    const fileNamePromise = doElasticsearchQuery(data);
    return fileNamePromise;
  });
  fileNamePromise.catch(err => handleError(err));

  const resultPromise = fileNamePromise.then(function (fileName) {
    // second callback
    const resultPromise = readMyFile(fileName);
    return resultPromise;
  });
  resultPromise.catch(err => handleError(err));

  return resultPromise;
}

The cool thing about promises is that they are designed to be chained. You can add callbacks to a promise chain with then(callback). The result is again a promise that resolves to the return value of the callback given to then(). If the callback returns another Promise, the promise returned by then will not resolve to this other Promise, but the value it resolved to. This enables chaining. And chaining avoids the deep nesting of pure callback approaches. Also, we can return something from handleRequest again. This time it's a Promise that resolves to result.

Chaining also works for errors! You can add an error callback with catch(callback). If an operation fails the closest error callback will be called. This helps a lot in our example because all our error handling code is the same.

We can write our example more elegantly. Firstly, we can eliminate the repetitive error handling and add the error handler only once. Secondly, we can use our I/O functions and the error handler directly as callbacks. This works because, e.g., the first callback in the code snippet takes data and returns a Promise resolving to fileName. This is exactly what doElasticsearchQuery is doing, which is why we can use it directly as an argument to then. We can do similarly for readMyFile and handleError.

function handleRequest() {
  return doDatabaseQuery()
    .then(doElasticsearchQuery)
    .then(readMyFile)
    .catch(handleError);
}

Promises have already helped tremendously in cutting down the complexity of callbacks. However, the resulting code is still a bit weird and not as clear as the synchronous equivalent. This is why async/await (and try/catch in async contexts) has been added to JavaScript!

async/await

async/await is so-called syntax sugar for promises. This means it gets compiled to promises by the JavaScript compiler before executing the code. And remember, promises are callbacks under the hood. Nothing magical about these things. So here is the example written with async/await.

async function handleRequest() {
  try {
    const data = await doDatabaseQuery();
    const fileName = await doElasticsearchQuery(data);
    const result = await readMyFile(fileName);
  } catch (err) {
    handleError(err);
  }
  return result;
}

As you can see, it looks very similar to the initial synchronous example. But actually, it is identical to the Promise version. This means you could replace the Promise version with this code and get the exact same function. Let's look at the differences to the initial synchronous example:

handleRequest became an async function
Use of the await keyword in front of the I/O functions. Even though they return promises, await turns those into the values they resolve to.
We return result directly. However, handleRequest will still return a Promise.

async will turn a function into an async function. This has two effects:

You can use await inside of async functions. Outside of them, you can't.
The return value of an async function is a Promise resolving to the value returned by the async function. Even if you don't explicitly return your async function will return a Promise that resolves to undefined.

await can only be used inside async functions (and JavaScript modules). It takes a Promise and turns it into the value it resolves to. It "waits" for value to be ready.

Furthermore, if there was an error and the Promise had no error callback attached, await will throw the error object that would have been passed as argument to the error callback. This makes error handling with try/catch easy and convenient.

Wrapup

I hope this showed how async/await fits into the I/O story for Node.js and JavaScript in general. It's just syntactic sugar for promises, which are themselves an abstraction over callbacks. This article just touches on the basics, though. I deliberately omitted important pieces of the puzzle, like error handling with promises, to keep it simple.

As a bonus, I will give some async functions and their identical twins implemented with Promises to show how the code is transformed.

async function f(x) {
  return x;
}

function f(x) {
  // resolve returns a promise that calls its callback immediately
  // with the value x. i.e. a promise that is immediately "ready"
  return Promise.resolve(x);
}

async function nothing() {
  // empty body
}

function nothing() {
  return Promise.resolve(undefined);
}

async function myFetch(x) {
  try {
    const data = await fetch(x);
    return data.toString()
  } catch (err) {
    return "fetch error";
  }
}

function myFetch(x) {
  return fetch(x)
    .then(data => data.toString())
    .catch(err => "fetch error");
}

async function parallelFetch(x, y) {
  const promises = [
    fetch(x),
    fetch(y),
  ]);

  // both fetches are being performed simultaneously in the background
  // (outside of the event loop, parallel to this code)

  // new promise that resolves when all given promises have resolved
  const bundlePromise = Promise.all(promises);

  // this will wait until both fetches are done
  const [resultX, resultY] = await bundlePromise;

  return { resultX, resultY };
}

function parallelFetch(x, y) {
  const promises = [
    fetch(x),
    fetch(y),
  ]);

  const bundlePromise = Promise.all(promises);

  return bundlePromise.then(([resultX, resultY]) => {
    return { resultX, resultY };
  });
}

Dates in JS

Florian Lackner — Tue, 21 Oct 2025 07:23:30 +0000

First posted here.

Date and time handling is arguably one of the most complicated things in computer science. It seems simple, since everybody knows how to read a clock or how to use a calendar. But the devil is in the details, as always. Since so many people seem to get it wrong over and over, we should talk about it.

In this blog post I want to offer a mental model to you. It created this famous click moment for me. Maybe it helps you too. Let me know, I'd be delighted.

Terminology

Let's give clearly defined names to the things we'll talk about. The topic is already complicated enough without confusion induced by the ambiguous nature of human language.

A Date is the information you can find on a physical calendar. It's a day, month and year.
A Time is the information you can find on a wall clock. It's an hour, minute and second. You can of course go finer by giving milliseconds etc.
A DateTime is a Date and a Time.
An Instant is a point in time on the planet. If two Instants are the same, this means that they happened at the same moment, physically speaking.
A Timezone is an algorithm to convert an Instant to a DateTime.

The key takeaway

A DateTime is NOT an Instant.

If you take one thing home today, it should be this. A DateTime is NOT an Instant. Neither can you convert between the two losslessly. They are fundamentally different concepts. In my opinion the confusion between the two is the cause of most bugs in date and time handling.

The mental model I'm offering is that these are different things that can't be converted without loss of information. You need to ask yourself every time which of the two you're working with and you can't mix and match them.

Let's use an example to show the difference. Say you're speaking on the phone with a friend who lives on the other side of the planet. Where you live it's maybe the evening, while your friend's about to start their day. Your DateTime is very different from your friend's DateTime. Yet, you're having a conversation at the same Instant in time. Of course, because you're saying something and your friend responds immediately (ignoring the slight delay imposed by the speed of light).

So let's repeat this again. A DateTime is NOT an Instant.

Timezones

Let's take the example further. Say you didn't have your conversation yet. Since you and your friend are both busy, you schedule it. Easy, you agree on an Instant in the future and be done with it. While it's true that you must agree on an Instant, it's unfortunately also true that people don't work on Instants. They work on DateTimes. How impractical. And since your friend lives far away, the DateTimes for the Instant of your call won't be the same.

You need to convert the Instant to a DateTime for each one of you. The algorithm to do so is called a Timezone. I'm saying algorithm, because Timezones are more than just a simple offset. There are complications like daylight saving time, leap seconds, and historical changes in time zones. I'd consider them black box algorithms, because they're complex and there's no shortcut around this fact.

Say you're living in France. Your Timezone is called "Central European Time" (CET) or Europe/Paris. Your friend lives in India. Their Timezone is called "Indian Standard Time" (IST) or Asia/Kolkata. You both agree on an Instant in the future. Then, you need to apply the respective Timezones to the same Instant to get your DateTimes. I've used India as an example, because its Timezone doesn't experience daylight saving time. In France, however, it does. So the way to calculate the DateTimes in each case are very different.

Universal Time Code (UTC)

The keyword "UTC" comes up a lot in discussions around time management. It is the name of a Timezone called "Universal Time Code". It is very often used to communicate Instants between actors in different Timezones. It has a special property that makes it very useful for storing Instants. It doesn't experience daylight saving time. This means that the conversion between Instants and DateTimes becomes reversible. Or in other words: A DateTime in UTC is equivalent to an Instant. You can convert between the two without loss of information.

Storage

So how do you store Instant, DateTime and Timezone ?

Instants can be stored as offset from a known Instant (epoch) in seconds. This is also called a timestamp. A common choice of the epoch is the Instant that corresponds to the DateTime Jan 1st 1970 at midnight in the Timezone UTC. The offset can be in seconds, milliseconds, etc. You can choose the granularity. This storage method is space efficient, since you only need to store one number.

DateTimes can be stored as strings or as Instant in UTC. There are several formats for the string representation. The most common format is the ISO 8601 format. It looks like this: 2023-03-15T12:34:56. This corresponds to March 15th, 2023 at 12:34:56. The Timezone is not specified in this example.

The second storage method is to store DateTimes as Instants in UTC. As already discussed, Instants in UTC map uniquely to DateTimes and vice-versa. This storage method is space efficient, since you only need to store one number. However, it is important to note that it is easy to make mistakes when using this method. You have to be very careful with your conversions.

Timezone values are usually stored as strings. There are standardized names for timezones. You should use these names. They are supported by libraries implementing Timezone.

`DateTime` or `Instant`?

Let's do some examples of when to use which for your information.

The time information of a log entry in a computer system: Instant, because it happens at a specific point in time.

Showing an Instant to a user: DateTime (obtained by applying the users Timezone).

A users birthdate: Date / DateTime , because that's what's written on their official documents.

The timing information of a one-off calendar event in a shared calendar: Instant, because it happens at a specific point in time. The Timezone of one user does not influence the Instant.

The timing information of a recurring calendar event. That's a tricky one. Think of every Monday at 2AM. What happens if the user changes their timezone? What happens on the day the clocks are reset for daylight saving time? Does the event happen twice? In my opinion there's no absolute answer here. It depends on how you want your system to behave. I'd store a DateTime + Timezone. I'd add code to handle the edge cases of the Timezone (using a library of course). And then I'd start praying.

The JS `Date` class

So what does the JS Date class represent? It's JS, so let's not be surprised by the answer: an Instant. Yes, that's the hard truth. And I want to be very clear: There is no Timezone information stored in the Date class. No UTC. It's an Instant. End of story.

But why does it have getters and setters for years, months, days, hours, minutes, and seconds? Because it's badly designed. And what do these return? They convert the Instant to a DateTime in the local Timezone of your user (frontend) or your server (backend). And then they extract the year, month, etc. and return them as numbers.

And here's another hard truth: Your users Timezone might be anything. You can't assume that:

it's correct.
it does / doesn't experience daylight saving time
its offset to UTC is positive / negative
it won't change

You need to code with this in mind.

I think the JS Date class should be avoided for anything related to DateTime. Instead, use one of the established libraries: Moment.js or Day.js. And in the near future, use the successor of Date, the new Temporal API.

How to write reviewer-friendly pull requests

Nico Prat — Fri, 17 Oct 2025 07:54:37 +0000

Reviewing someone else's work is often challenging and time-consuming. It can easily lead to procrastination, frustration, or even tension between developers. Yet, it's an essential part of our daily workflow and deserves careful attention.

Below are a few unordered tips we've gathered over time to make reviewing pull requests easier (from the author's perspective) to help prevent issues before they arise.

We use GitHub, so some examples are specific to it, but the same ideas apply to most alternatives.

1. Write small pull requests

This is the most common (and probably the most important) advice. To reinforce it, we automatically add t-shirt-sized labels to our pull requests. This encourages authors to keep them short and reassures reviewers that the review won't take too long.

2. Always prioritize readability

This applies not only to the codebase itself but also to the files diff. Don't hesitate to add code comments that provide context (eg. data format examples) even if they seem redundant with TypeScript types or equivalents. Anything that helps someone understand the code outside of an IDE is worth including.

3. Create a simple template

Use GitHub pull request templates to make authors' work easier and ensure consistency across pull requests. A short template with three or four sections (and maybe a few checkboxes) is often enough to remind authors of key steps in the process.

4. Explain why it's done in the description

Include any relevant specifications, documentation, or conversations related to the pull request. This not only helps the reviewer but can also help yourself realize if something has been overlooked (which happens more often than we'd like to admit). Plus, even if the reasoning seems obvious now, it will help future developers understand the decision (especially years down the line). Obviously, make sure to explain how the feature is supposed to work.

5. Explain how it's done in the files diff

Before requesting a review, review your own diff. You might catch accidental commits, hard-to-read code, or even mistakes. It's frustrating for reviewers to find easily avoidable errors. Also, force yourself to add helpful comments in the diff: I personally often find that they actually belong to the code itself and add a commit for them.

6. Help the reviewer with tips

I often add "guided tour" comments in the diff, like suggesting to "review with whitespaces ignored" or to "review commit by commit". These small hints can make the process much easier. You can also mark some code lines that are open to discussion or feedback. Encourage the reviewer to be part of the collaboration, not just a gatekeeper.

7. Make a unique commit for renaming or moving files

Whenever you rename or move files, make it a separate commit from content edits. (Git and GitHub sometimes detect this automatically, but not always.) This allows reviewers to skip the rename commit and focus on the real changes, instead of a massive "deleted and added" diff. This practice made our TypeScript migration much smoother for instance.

8. Rebase commits

Coding is rarely linear, mistakes are made, sometimes fixed a few days afterwards. Before opening a pull request, consider taking some time to rebase commits to make the history more readable. Don't try to make it perfect, but at least regroup commits that belongs together so it makes more sense when reviewed.

9. Suggest a pair review if necessary

For complex pull requests or ones that require intricate setup, a pair review might be faster and more productive. It's also a great opportunity to explain your code out loud: often, you'll discover parts that are hard to justify or could be simplified.

10. Kill your ego

Take feedback with an open mind. Make reviewers feel appreciated for the time they spend on your work. This way, they'll be more eager to review for you again. Remember that it's usually more valuable to make the reviewing process smooth and collaborative than to be "right" at all costs. That's easy to forget when we're deep in the work.

I hope those tips can help making this complex task smoother in your daily workflow!

Automatically take care of outdated browsers thanks to Browserslist and Github Actions

Nico Prat — Mon, 28 Jul 2025 08:46:32 +0000

Our policy is to support browsers released within the last two years. Previously, we used Browserslist to transpile our code and automatically add polyfills. At some point, we wondered if we could use the same configuration to inform users when their browser was too old — ideally, without needing to write or maintain that logic ourselves.

It's all in a regex

Fortunately, there's a package that does exactly that: browserslist-useragent-regexp. It generates a regular expression based on your Browserslist config, which you can run against navigator.userAgent.

Here’s a simple .browserslist.rc config targeting our policy:

last 2 years
not dead

Then, you can generate the regex using a script in your package.json:

{
  "scripts": {
    "supportedBrowsers": "npx update-browserslist-db@latest && echo \"export default $(browserslist-useragent-regexp --allowHigherVersions);\" > supportedBrowsers.js"
  }
}

The npx update-browserslist-db@latest command ensures your caniuse data is current, preventing the dreaded Browserslist: caniuse-lite is outdated warning.

This script outputs something like:

export default /Edge?\/(10[5-9]|1[1-9]\d|[2...

You can then import and use this regex in your app to notify users:

import supportedBrowsers from './supportedBrowsers.js'

if (!supportedBrowsers.test(navigator.userAgent)) {
  alert('Your browser is not supported, please update it.');
}

Automate the update

To keep the regex up to date, we use GitHub Actions to run the script automatically every month. That way, our last 2 years policy always reflects the current calendar without anyone needing to remember to update it.

Here’s a simplified version of our workflow:

name: CI - Update browsers list

on:
  schedule:
    # At 8:00AM UTC the first day of the month
    - cron: "0 8 1 * *"

jobs:
  update_frontend_browserslist:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Update browsers list
        working-directory: components/frontend
        run: npm run supportedBrowsers

      - name: Commit and push changes if any
        run: |
          git config user.name Internal
          git config user.email internal@yourcompany.com
          # Check if there are any changes to the browsers list
          if [[ -n "$(git status --porcelain .)" ]]; then
            git add .
            git commit -m "chore: update supported-browsers.ts"
            git push
          fi

With this in place, we get a fresh, accurate regex every month — keeping users informed only when necessary, without adding manual work for the team.

Live Coding in Kubernetes: How we debug production data remotely with Tilt

Kilian Decaderincourt — Tue, 01 Jul 2025 09:00:48 +0000

tldr: We use Tilt to enable developers to live-edit code running directly on our remote Kubernetes cluster, allowing them to debug issues on realistic production data from their local IDE. It plays nicely with our multitenant model, allowing developers to target and replace specific tenant services while keeping everything else running.

What Tilt does

First, a quick recap on what Tilt does if you're not familiar with it. Tilt is a tool that lets you describe your dev environment as code to run on Kubernetes and start it in a single command with smart rebuild and live updates.

Let's say you have a Dockerized app you want to test. If you do this manually, you need to first build the Docker image, push it to a repository then create a pod using this image. In its simplest form, Tilt will automate all these steps and do it on every change. It also comes with a nice UI to visualise everything and stream your pod logs.

You can also go further with it and instead of rebuilding on every file change, you can configure Tilt to sync specific files directly inside the pod. Possibilities are almost endless due to it being easily configurable with some Python scripting.

Our architecture

As an HR B2B SaaS provider, ensuring data segregation between our customers is very important, you wouldn't want your employee to receive an internal mobility offer.. from a different company. This has a significant impact on how we design our architecture. Each customer gets their own database, S3 storage container, Elasticsearch indexes, Redis namespace, DNS record, etc.

This is what we call a tenant. Each customer has a production tenant for their employees, optionally one or more sandbox/test tenants, and a corresponding staging tenant. Developers also get their own tenant in the development environment. Overall, we have over 200 tenants spread across 3 environments each with its own purpose.

To work at that scale, most of our application components are multitenant, meaning a single deployment can handle multiple tenants. That's the case for the data science backoffice components or our frontend application. However, for historical reasons, some components like our API backend have always been developed to serve a single tenant, so it requires a distinct deployment per tenant.

How we're using it

Instead of using Tilt on a local Kubernetes cluster, like what seems to be the most used scenario, we use it directly on our remote cluster hosted on Azure. The main benefit for us is that we can hijack any tenant pods and make them use a different code that can then be edited in real-time from a local IDE on our laptop.

When starting Tilt, it builds an image per component, pushes it to our repository and deploys pods using this image in the namespace of the selected tenant. Pods deployed by Tilt reuse all the Secrets and ConfigMap already provisioned and updated by the infrastructure to connect to the right database, S3 bucket, etc.

For components handling a single tenant, like our API backend, Tilt will first call a script to stop it by scaling it down to zero, which avoids any background running tasks that could edit data. Whereas components shared with other tenants like the frontend, are not stopped, instead Tilt will create a new pod in the tenant namespace and create a new Ingress with a higher priority that will route requests to our new frontend and backend pods.

To leverage the live update feature and avoid rebuilding on every change, the images are not the same as the prod one. For example, our frontend image uses a Node.js-based image to run the Vite server instead of serving compiled assets with nginx. Every step above is described in the Tiltfile either using built-in functions or a call to custom scripts.

tilt up -- --tenant-name tenant-a

For obvious reasons, we don't allow tilting directly onto the production tenant, instead we first make a copy of it. This process would merit its own blog post but in essence, each of our production tenants have a corresponding staging tenant in a lower environment. We can copy on demand all the tenant data and import it into the staging tenant with a layer of anonymisation for personal information like email, names and avatars. This lets our developers investigate issues and debug them in their development environment with real data, making the reproduction of bugs much easier.

Each developer has their own tenant in the dev cluster so they can use Tilt for day-to-day development work. The code runs on the remote cluster while their IDE stays on their local laptop. To limit the cost of this environment, we run everything on Azure spot instances. Not everyone at 365Talents is using Tilt as their standard development workflow, some prefer the more local solution based on Devcontainers. Either way, Tilt is used by everyone when they need to debug things on a staging tenant.

Advantages

Running code on realistic data

Due to our customers' different use cases, their data is highly heterogeneous depending on the features they use or not. The main advantage for us is the ability for a developer to plug themselves to a specific tenant and edit the code that is run in real time on a realistic dataset.

Production similarity

When developing with Tilt, your setup ends up closer to what is happening in production than if you were on your laptop. The code runs in the same place and almost in the same image. The requests go through the same network components.

Fewer resources used on laptop

Another benefit is to consume less resources on the developer laptops as every service is run remotely in our cloud, this lets more resources available for their IDE and linter.
While not a main concern for our web developers in the stack that was presented in this article, this is more important for our data science team. They also started using Tilt for their own stack running 6 differents data services hungry in memory and computing power.

Difficulties

Wrapper script to switch context

One of the Tilt limitations for security reasons is that once Tilt is started, it cannot switch to another Kubernetes context. For our use case, we had to create a wrapper script to be able to only specify the tenant we want to tilt to without worrying about which cluster it's on. The script simply finds the corresponding cluster based on the requested tenant and starts Tilt with the correct Kubernetes context.

Slow cold start

This one is from our all remote approach, pushing the image to the repository is dependent on the network speed and can take a while. Since the first introduction there have been multiple iterations and attempts to improve this.

This includes optimizing the Dockerfile order to reuse existing layers, tweaking the docker config to use the repository as a build cache, even trying to remove npm dependencies from the image and downloading them at startup or storing them in a PVC. Each comes with its own drawback, overall this is still a persistent problem. It shouldn't be as long as we don't do a full rebuild very often..

Too many uncontrolled full image rebuilds

Despite our best efforts, there are still too many times when a full rebuild is triggered. This mainly occurs when switching branches with lots of changes. This is a persistent pain point that we haven't truly solved yet.

Initial friction with Kubernetes

Having control over their development environment is very important for developers. When we introduced Tilt, our Kubernetes migration for all our services was done recently, so they were still unfamiliar with some Kubernetes concepts. This also contributed in a good way to them becoming more comfortable with Kubernetes in the end. They have more control over it now and are the ones editing and improving the Tiltfile.

Conclusion

Despite the challenges, Tilt has become an integral part of our development workflow. It lets target a single one of our tenant and edit the code running live inside our Kubernetes cluster. Once combined with our process to make a copy of the production data, developers can easily debug issues from the comfort of their local IDE directly on realistic data. We could make it fit our needs thanks to its great customizability.

References

Tilt - The official Tilt website with documentation, tutorials, and download links
365Talents - Adaptive Skills & Talent Intelligence for ambitious HR.
365Talents Jobs - Join us !

Automating GitBook translations with GitHub Actions: A complete guide

Arthur Dufour — Mon, 10 Mar 2025 14:07:07 +0000

Introduction

GitBook is a modern documentation platform that makes it easy to create, edit, and organize documentation. With its clean interface, version control, and collaboration features, it's no wonder it's become so popular among development teams.

But if you're managing documentation with GitBook and need to support multiple languages, you've probably hit a major roadblock: GitBook doesn't offer native translation capabilities. While it's fantastic for creating and managing documentation, this lack of built-in translation features can be a real headache for international teams.

In this article, I'll share a complete solution for automating GitBook translations using GitHub Actions and a custom Node.js script. As a fullstack developer who recently implemented this for the startup I work at ; 365Talents, I discovered that while GitBook does provide some documentation on translation workflows, it lacks the concrete implementation details you need to actually get it working.

This guide is for you if you:

Use GitBook for documentation
Need to maintain content in multiple languages
Want to automate the translation process
Have basic familiarity with GitHub Actions & Node.js

By the end, you'll have everything you need to build a fully automated system that detects changes to your primary language content and automatically translates it to your target languages.

Defining your requirements

Before diving into implementation, you need to make two important decisions about your workflow:

Translation review process: While automated translation has improved dramatically, it's still far from perfect. You'll need to decide how translations will be reviewed and by whom. GitBook's documentation points out something crucial: when a reviewed translation exists and the source document is updated, automatic re-translation will overwrite any manual improvements made during review. Your team needs a clear process to handle these situations.
Update strategy: You must decide how to handle updates to existing content.
For our implementation, we took a conservative approach: we only automatically translate new documents, not updates to existing ones. This preserves any manual edits made to translations but means content authors need to manually update translations when they modify the primary language version. While this approach isn't perfect for multilingual content management, it worked best for our specific needs.

You can enhance your translation process in many ways. For instance, you could just retranslate the specific phrases that changed instead of the entire file, though this would require more development work.

Solution Overview: Automated translation workflow

The solution I'm sharing creates an automated pipeline that:

Detects new files added in your primary language
Translates them using a translation service (Azure Translator)
Creates the corresponding content in your target language spaces
Commits the changes back to your repository, automatically updating GitBook

Step 1: Setting up GitBook with GitSync

Before we can automate translations, we need to set up GitBook properly and connect it to GitHub using GitSync.

Creating a Collection with language Spaces

In GitBook, collections let you group related spaces together. For our translation workflow, we'll create a collection with a separate space for each language:

Create a new collection in GitBook
Create a space for your primary language (e.g., "English")
Create an additional space for your target language (e.g., "French")

Configuring GitSync

Next, we need to connect each space to our GitHub repository:

Go to your space settings
Navigate to the "Integrations" tab
Select "GitHub" and follow the authentication process
Configure the sync settings:
- Select your account and repository
- Choose the branch (usually "main" or "master")
- Use the monorepo approach and specify the folder path for your language (e.g., ./en for the "English" space, and ./fr for the French space)

Repeat this process for your target language space, making sure it's connected to the appropriate folder in your repository.

Repository structure

After setting up GitSync, your repository structure should look something like this:

/
├── en/           # Primary language content (English)
├── fr/           # French translations
└── .github/
    └── workflows/
        └── translate.yml  # Our future GitHub Action workflow

This structure makes it easy to manage content for each language separately while keeping the automation in a central location.

Step 2: Creating the GitHub Action workflow

Now, let's create the GitHub Action workflow that will detect changes and trigger our translation process.

Create a file at .github/workflows/translate.yml with the following content:

name: Translate GitBook Content

inputs:
  source_language:
    description: "The source language (e.g.: en)"
    required: true
  target_language:
    description: "The target language (e.g.: fr)"
    required: true
  translator_api_key:
    description: The Azure Translator API key
    required: true

runs:
  using: composite
  steps:
    - name: Get all changed markdown files
      id: changed-markdown-files
      uses: tj-actions/changed-files@v45
      with:
        files: |
          ${{ inputs.source_language }}/**/*.md

    - name: Get all changes in .gitbook/
      id: changed-gitbook-files
      uses: tj-actions/changed-files@v45
      with:
        files: |
          ${{ inputs.source_language }}/.gitbook/**

    - name: Copy .gitbook files to target language directory
      shell: bash
      if: steps.changed-gitbook-files.outputs.any_changed == 'true'
      run: |
        rm -rf ${{ inputs.target_language }}/.gitbook
        mkdir -p ${{ inputs.target_language }}/.gitbook
        cp -r ${{ inputs.source_language }}/.gitbook/* ${{ inputs.target_language }}/.gitbook/

    - name: Setup Node.js
      if: steps.changed-markdown-files.outputs.any_changed == 'true'
      uses: actions/setup-node@v4
      with:
        node-version: 23.6.0

    - name: Set up pnpm
      if: steps.changed-markdown-files.outputs.any_changed == 'true'
      uses: pnpm/action-setup@v4
      with:
        version: 9.14.2

    - name: Install dependencies
      shell: bash
      if: steps.changed-markdown-files.outputs.any_changed == 'true'
      working-directory: 365talents-actions/actions/gitbook-translator/translator-script
      run: pnpm install

    - name: Run translation script
      shell: bash
      if: steps.changed-markdown-files.outputs.any_changed == 'true'
      working-directory: 365talents-actions/actions/gitbook-translator/translator-script
      env:
        SOURCE_LANGUAGE: ${{ inputs.source_language }}
        TARGET_LANGUAGE: ${{ inputs.target_language }}
        NEW_FILES: ${{ steps.changed-markdown-files.outputs.all_changed_files }}
        TRANSLATOR_API_KEY: ${{ inputs.translator_api_key }}
      run: node index.ts 

    # Make sure that deleting a file in the source_language also deletes it in target_language
    - name: Cleanup deleted files
      shell: bash
      run: |
        cd ${{ inputs.target_language }}
        find . -type f -name "*.md" | while read file; do
          if [ ! -f "../${{ inputs.source_language }}/$file" ]; then
            rm "$file"
            echo "Removed ${{ inputs.target_language }}/$file as it no longer exists in ${{ inputs.source_language }}/"
          fi
        done

    # Commit translated content
    - name: Commit changes
      uses: stefanzweifel/git-auto-commit-action@v5
      with:
        commit_message: Translate files
        file_pattern: '${{ inputs.target_language }}/**'
        add_options: --all

This workflow:

Triggers on file changes
Uses tj-actions/changed-files to detect which files have changed
Checks out the repository and sets up Node.js
Runs our translation script (which we'll create next)
Commits the translated files back to the repository

Step 3: Implementing the translation script

Now we need to develop the Node.js script that will perform the actual translation work. This script is the heart of our automation system, responsible for:

Processing the detected file changes
Communicating with the translation API
Saving the translated content

I've created a complete implementation of this translation script and shared it in a GitHub Gist for you to reference: GitBook Translation Script

The script uses Azure Translator API to convert content between languages, but you can easily modify it to work with other translation services like DeepL, Google Cloud Translation, or OpenAI if those better suit your needs.

One critical aspect of the translation script is how it handles Markdown syntax. The Azure Translator API sometimes loses Markdown formatting during translation. To fix this, the script uses regular expressions and string replacements to preserve all Markdown syntax elements after translation.

Remember that this implementation reflects my team's specific requirements and workflow. You should review and customize the code to match your team's translation strategy, especially regarding how you want to handle content updates and translation reviews.

Step 4: Committing translated content back to the repository

The GitHub Action workflow automatically commits the translated files back to your repository. GitSync then updates your GitBook spaces with the new content. You have nothing more to do! 😄

Advanced Customizations

Supporting multiple target languages

My script currently only supports one target language, but it can easily be adapted to handle multiple target languages.

You would need to:

Add more GitBook spaces and configure GitSync correctly for each language
Update the translation script to loop through all target languages
Modify the GitHub Action to support multiple target languages

Implementing manual review workflows

Currently, the described setup doesn't include a manual review process, meaning all new files are automatically translated and instantly added to GitBook.

To implement a manual review process, you could:

Create a pull request instead of directly committing translations
Add reviewers to the pull request
Only merge after approval

Optimizing for large content bases

Our setup only translates new files, which isn't ideal for frequently updated documentation. If you regularly make changes to your documentation, you'd need to implement incremental translation to process only the content that has changed.

Translation quality considerations

Azure Translator, like other machine translation services, works well for most general content but may struggle with:

Technical terminology specific to your product or industry
Complex sentence structures
Idiomatic expressions
Cultural nuances

For technical documentation, you might notice certain specialized terms being translated incorrectly or inconsistently across documents.

Beyond manual review, here are several strategies to enhance your translation quality:

Custom Dictionary/Glossary: Create a glossary of technical terms and their approved translations. Some translation APIs (including Azure Translator with Custom Translator) allow you to provide custom dictionaries.
Pre-processing Content: Simplify complex sentences in your source content. Clear, concise writing translates better.
Post-processing Scripts: Develop scripts that automatically correct known translation issues, such as consistently replacing certain terms with their correct translations.
Translation Memory: Implement a translation memory system that stores previously approved translations, allowing you to reuse them for similar content.

Cost considerations

When implementing an automated translation system, it's important to consider the costs involved, especially as your documentation grows.

A few things to keep in mind:

Compare service costs before committing to one provider
Implement cost optimization strategies (only translate sections that have changed, store and reuse translations for repeated content)
Monitor your usage and set up alerts to avoid unexpected costs as your documentation grows

Conclusion

Setting up this GitBook translation system was honestly not that simple to do. GitBook really should just build this in. In my opinion, documentation is global, and teams shouldn't have to hack together custom solutions for something so fundamental.

Until then, this solution works well enough to save you from manual translation headaches. It's not perfect, but it's definitely better than copying and pasting content between languages!

What we learned by running an accessibility audit of our app

Nico Prat — Tue, 11 Feb 2025 13:30:06 +0000

We recently underwent an accessibility audit (thanks to Access42) for our app due to compliance regulations for large companies in France. Initially, we believed we were in good shape because we use modern tools, adhere to basic HTML structures, and avoid unusual ergonomics.

However, we decided to invest effort into this area as we needed to meet a minimum score, and the scoring system is quite stringent: any failure on a specific criterion on any audited page counts as a failure, which can quickly degrade the overall score.

That's when we realized just how poor our accessibility was, how complex the subject is, and how much work lay ahead of us...

Before diving in

As a typical developer, I initially believed that accessibility was merely a technical issue to be resolved. However, I soon realized I was mistaken, and I would like to share our experience before delving into more concrete details.

Get a proper training

It's easy to assume that accessibility is straightforward, but like everything in web development, there's a rich history, numerous quirks, and backward compatibility issues that complicate matters.

Fortunately, four developers and I had the opportunity to participate in a three-day training session, including hands-on testing of our own app. This was incredibly instructive. We were able to experiment with tools and ask questions on the spot, which was far more efficient than spending hours on Stack Overflow trying to figure out why VoiceOver wasn't behaving as expected...

Involve every stakeholder

A web app should be designed with accessibility in mind from the outset, much like performance and other cross-cutting concerns. While developers can implement fixes, these solutions are often less effective for users and require more effort from the team. Examples include manually adding aria-label attributes to icon-only buttons, creating textual alternatives for complex objects, and managing focus states manually when informations are spread on the interface.

Certain design-specific aspects, such as text size, color contrasts, and considerations for color blindness, cannot be addressed by developers alone. Currently, here, developers are primarily responsible for ensuring the accessibility of the product through testing. However, we hope that a culture of accessibility will gradually permeate all aspects of our work over time.

Understanding the accessibility tree

You might already be familiar with the DOM (Document Object Model) and CSSOM (Cascading Style Sheets Object Model), but we discovered that there is another, less visible underlying model: the accessibility tree.

It is primarily derived from HTML elements and results in four properties for each element:

name: a kind of identifier
description: a secondary string describing the element, similar to a tooltip
role: one of the list of roles. By default, it is generic; a button will be button, an a will be link, and it can be overridden by the role="" attribute.
state: indicates if the element is currently active, expanded, pressed, checked, etc.

Understanding these properties is crucial for correctly using attributes like aria-label, title, aria-describedby, and so on, as well as knowing their priority. For example, aria-labelledby takes precedence over aria-label. Modern browsers now offer a view of the accessibility tree in their developer tools, making it easier to debug. More on this later.

Subjectivity

One final note before diving in, regarding what may be the most challenging aspect of accessibility: subjectivity.

Here are some scenarios where it can be difficult because no tool can help you make a decision:

Should this text be a heading or a paragraph?
An image has an alt attribute, but is it truly meaningful?
A "skip" button has been added, but is it genuinely useful??
Should this notification be polite or assertive?

In short, even a 100% accessible website could be frustrating to use with a screen reader. The best way to assess this is to use it ourselves under "real" conditions. The only downside is that it's time-consuming, so I suspect few companies actually do it.

Using accessible librairies

Chances are that you rely on a UI library for common components. You first want to make sure it's already accessible enough, or else you'll lose a huge amount of time trying to fix errors that you don't actually control. In our case, we're migrating from ElementPlus to Radix Vue mainly for this reason.

It seems modern tools finally treat accessibility as a first class citizen, but it was not the case just a few years ago! Ark UI looks like a good alternative too. You can check their docs and even use the tool below to check its accessibility compliance.

We can also refer to Offical WCAG rules for simple and framework-agnostic examples.

Manual testing

Now that we have the basic theory, it's time to get our hands dirty and find issues and test fixes. Here are the main tools we used:

Browser accessibility devtools

Browsers have come a long way in terms of tooling, and it's really helpful to understand the state of a specific element and why it's considered that way. For instance, the aria-label attribute takes precedence over the title attribute, so Chrome indicates that it will be ignored:

It's not as clear in Firefox, but other information is provided:

Each browser offers different tools with their own advantages and disadvantages, so feel free to try them out to find your preferences.

Axe browser extension

Axe is probably the most well-known suite of tools for testing and improving accessibility. It is essentially included in every major testing solution, as we'll see next.

You can find the Axe extensions for browsers on their website (available for Chrome, Firefox, and Edge). It offers a lot of tools to identify accessibility issues:

While it might not be the most feature-complete, as indicated in this study by the British Government, it is probably better to have consistent test results across your tools (unit tests, manual tests, E2E tests, etc.) than ultra-exhaustive error reports.

Windows, Firefox & NVDA

This setup is the most widely used worldwide, and NVDA is the most valid and feature-complete free tool available, so it should be preferred when doing tests. If you're on Mac, you can use a virtual machine (we chose Parallels Desktop with Windows 11, which took about 30 minutes to set up and ~130€ one time payment).

MacOS, Safari & VoiceOver

VoiceOver is included in every Mac and can be toggled by pressing CMD+F5. It's pretty good by default, but it is known to have some quirks. For instance, it won't read aloud any alert that uses anything other than alert (log or status won't work). If you're on Windows, unfortunately, there's no way to emulate it locally.

Using BrowserStack

Online virtual machines can be useful too. We didn't try them, but BrowserStack currently supports screen readers, and there could be other tools offering similar functionality.

Automated Testing

Unit Tests

We believe unit tests are not particularly useful for accessibility, as checking only for HTML attributes is generally insufficient. Tools like Axe can handle this better than manual unit tests, so we didn't use them at all.

End-to-End Accessibility Tests with Cypress

End-to-end tests are better suited for accessibility checks because they closely mimic what users will see and interact with. However, there are some quirks with Cypress, such as handling tab keys to check for focus. You might want to look into cypress-real-events for a potential solution. (Edit: It seems like this issue is finally being considered in Cypress priorities).

I suppose Playwright might not suffer from those issues as it uses a different, more native way of controlling the browser, but we don't use this tool directly for now.

Axe Plugin

We used the cypress-axe plugin to easily integrate Axe into our tests. The upside is that it's straightforward to use; the downside is that reading errors can be challenging (clicking on lines provides better feedback, though):

Cypress Cloud accessibility add-on

Luckily for us, Cypress released a full featured accessibility add-on not so long ago.

It relies on Axe too, but it's much more integrated in the ecosystem. For instance, the online report is very nice (I can't expose the visual of our app unfortunately):

Also, the Slack integration is quite nice too:

The obvious downside is that it's a paid add-on, and it's quite expensive 🥵 so we probably won't be able to keep it in our suite.

Specific Tests

For more specific tests that don't rely on rules covered by Axe, you can add some manual checks. For example:

The first tab should show and focus a "skip to content" link.
After opening a dialog, its first input should be focused.
A notification should be shown once an action is completed (also check its attributes to ensure it will be announced by screen readers).

You can easily find the focused element in Cypress by running cy.focused().

Component Accessibility Tests with Storybook

Storybook proved to be really useful for accessibility testing. It's easier to set up than end-to-end (E2E) tests but still provides visual feedback and debugging tools. It also allows for complex cases where components are used together or under special conditions. You can write specific play functions that use any code or components you need, not just the one being tested.

By the way, Storybook uses Testing Library, which you can think of as an element selector tool with accessibility in mind. For instance, it won't let you retrieve an element by its class name but forces you to check its role or name (remember the accessibility tree we talked about above?). This is because we should test what the user faces, not the underlying code. It might seem like a small detail, but it sets you in the right mindset when testing.

Lastly, Storybook uses Playwright under the hood, so it actually controls the browser instead of creating fake events in JavaScript like Cypress does. This makes it easier to work with native interactions like tabbing, which is huge for accessibility.

Axe Plugin

Once again, Axe is part of the solution with an official accessibility plugin. It provides a checkA11y() function that can be set up to run automatically at the end of every test or manually called in a specific test (using the play() function in Storybook with the addon interactions). Here's a truncated example of what can be done:

// In the config
const config = {
  async preVisit(page) {
    await injectAxe(page);
  },
  async postVisit(page, context) {
    await checkA11y(page, 'body', {
      detailedReport: true,
      detailedReportOptions: {
        html: true,
      },
    });
  },
};

// In the story
export const Default: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    canvas.getByRole('button', { name: 'Show a notification' }).click();

    const notification = canvas.getByRole('alert');
    expect(notification).toBeInTheDocument();
    expect(notification).toHaveTextContent('This is a notification message!');

    // Accessibility tests will be run automatically here
  },
};

Again, it's pretty straightforward to set up. Errors in the interface are clear and actionable as shown below, but it's hard to read in the CI (GitHub Actions in our case) and we didn't spend time to try to improve it for now:

Specific Tests

We especially appreciated Storybook for running our own specific tests. For instance, we had a hard time ensuring that tooltips were used correctly (tooltips are much harder to get right than we initially thought). So, we interacted with the trigger element by focusing it or not and checked that everything was working as expected:

play: async ({ canvasElement }) => {
  const canvas = within(canvasElement);

  const target = canvas.getByText('Hover me to show tooltip');
  // Check tabindex to be sure it's focusable
  await expect(target).toHaveAttribute('tabindex', '0');

  canvasElement.focus();
  await userEvent.tab();
  expect(document.activeElement).toEqual(target);

  const tooltip = canvas.getByRole('tooltip', { name: 'Hello world!' });

  await expect(tooltip).toBeVisible();

  // Check role button to be sure it's read by screen readers
  await expect(target).toHaveAttribute('role', 'button');
},

Another case was ensuring our focus trap always worked within an open dialog. We used the same mechanism to check that we looped through interactive elements without tabbing out.

Linting

ESLint can also help developers avoid simple mistakes early in the development process. We use the ESLint plugin VueJS accessibility, but there are alternatives for other major libraries. While it is the least capable of all the tools we listed, it offers the quickest feedback loop, making it ideal for simple cases.

We had to enforce and create custom rules for our specific use cases to ensure components are used correctly. For instance, our <Tooltip> component should have its interactive element as a direct child, like a <Btn>. We leveraged the vue/no-restricted-syntax rule as follows:

'vue/no-restricted-syntax': [
  {
    selector: 'VElement[rawName="Tooltip"] > VElement:not([rawName=/^(a|router-link|button|Btn)$/]) VElement[rawName=/^(a|router-link|button|Btn)$/]',
    message: 'Interactive elements should be the direct child of a tooltip, or its content will not be read aloud by screen readers',
  }
]

Conclusion

It's virtually impossible to achieve 100% accessibility on a complex web app. Companies that claim otherwise are likely mistaken, whether intentionally or not. Some conduct their own internal audits, which are clearly not as reliable as those performed by an external, independent organization.

We also discovered that there are some difficult and almost undocumented quirks. For instance, a tooltip must be set on an interactive element to be actually announced (e.g., with an implicit or explicit role of button or link; a span would be ignored) and I didn't see documented in common posts and examples. Therefore, the rule is to always test manually and not rely solely on green CI checks for the right attributes.

It must also be said that an audit is outdated as soon as it's done, as nothing prevents the code from changing from that date. In France, an accessibility declaration is only valid for a few years, and it must be rechecked when the website is "substantially" updated, which is quite subjective.

So, the "best effort" technique is the only way to go, and accessibility must be treated with sincerity to be achieved at its best. This involves truly treating it as an acceptance criterion, training developers and designers (and every stakeholder, by the way), having automatic tests, and using manual tools.

Finally, the Accessibility Object Model (AOM) is an experimental JavaScript API that allows interaction with the accessibility tree directly without using attributes, such as button.accessibleNode.expanded = true. This could greatly help developers, as it would eliminate the need to rely on easy-to-break IDs everywhere. However, as everything accessibility related, it might be years before it is widely supported...

Customize TypeScript syntax highlighting in VSCode

Nico Prat — Tue, 07 Jan 2025 18:11:18 +0000

TL;DR show me the code

TypeScript can be intimidating at first glance, especially when you're used to the relative simplicity of JavaScript (or allergic to the verbosity of other languages you might have studied, like me with Java). When I started learning it a few years ago, I found the code harder to scan, as if everything was slightly less readable.

I then searched for a way to better distinguish new code from existing code, and started exploring how VSCode handles visual themes.

Editor Tokens & Scopes

Similar to an Abstract Syntax Tree (AST), VSCode breaks down the code in each file into tokens to create an abstract view of it, making it easier to manipulate. This abstraction is then used to build themes and analyze the code.

To better understand this functionality, there are guides on syntax highlighting and semantic highlighting. The former focuses on static analysis, while the latter understands the code (for example, recognizing that a variable is actually a parameter and thus ensuring it retains the same color for consistency across occurrences):

Simply put, each character in your code is assigned:

A token type: String, Comment, ... (complete list here)
One or more scopes, which act like subsets or groups

Extensions can add new scopes, for example, for Vue files (Single File Components), which contain HTML, JavaScript, and CSS.

Customization

To help us understand this system, VSCode offers a command "Developer: Inspect Editor Tokens and Scopes" that displays a tooltip with information about the currently selected code. Here's an example with the compact function from Lodash:

There’s a lot of information, but the only thing we care about for now is the list of scopes; the most specific scopes are listed first. We can use these to target the elements we want to customize.

Next, we move on to the VSCode settings to adjust the theme to our needs. The documentation explains that you need to edit your settings.json file as follows (use the "Preferences: Open User Settings (JSON)" command):

{
  "editor.tokenColorCustomizations": {
    "textMateRules": [
      {
        "scope": [],
        "settings": {}
      }
    ]
  },
}

As I navigated through the code over the weeks and experimented with rule specificity, I came up with this list of scopes (which is likely not exhaustive):

{
  "editor.tokenColorCustomizations": {
    "textMateRules": [
      {
        "scope": [
          "support.type.builtin.ts",
          "meta.interface.ts punctuation.definition.block.ts",
          "meta.type.annotation.ts",
          "meta.type.declaration.ts",
          "entity.name.type.ts",
          "support.type.primitive.ts",
          "entity.name.type.alias.ts",
          "entity.name.type.interface.ts",
          "storage.type.interface.ts",
          "keyword.operator.type.annotation.ts",
          "punctuation.definition.typeparameters.begin.ts",
          "punctuation.definition.typeparameters.end.ts",
          "meta.object.type.ts",
          "meta.type.parameters.ts",
          "meta.object.member.ts meta.type.tuple.ts",
          "keyword.control.satisfies.ts",
          "keyword.control.as.ts",
          "meta.type.declaration.ts punctuation.definition.block.ts",
          "meta.type.declaration.ts keyword.operator.assignment.ts",
          "meta.type.parameters.ts punctuation.separator.comma.ts",
          "meta.type.parameters.ts punctuation.definition.block.ts",
          "meta.type.parameters.ts meta.brace.square.ts",
          "meta.type.annotation.ts keyword.operator.type.ts",
          "meta.type.annotation.ts punctuation.terminator.statement.ts",
          "meta.type.annotation.ts punctuation.definition.block.ts",
          "meta.type.annotation.ts string.quoted.single.ts",
          "meta.return.type.arrow.ts meta.type.tuple.ts",
          "keyword.operator.definiteassignment.ts",
          "keyword.operator.optional.ts",
          "storage.type.type.ts",
          "meta.interface.ts"
        ],
        "settings": {
          "fontStyle": "italic",
          "foreground": "#ff0000"
        }
      }
    ]
  },
}

As you can see, all scopes end with .ts, and scopes can be further refined to ensure they’re nested within another using a space (similar to a CSS selector): "meta.type.annotation.ts keyword.operator.type.ts".

The only thing left is to decide which styles to apply. Unfortunately, the options are limited: just text color and a few font styles (bold, italic, underline, strikethrough), or a combination of these. To avoid color conflicts with a theme, I chose to apply italics, which remain fairly discreet in daily use. I had considered using a very light background color, but this still isn’t possible in VSCode (open ticket since 2016).

Here’s the result on an example from the TypeScript documentation with "fontStyle": "italic":

{width="495"}

Feel free to find what works best for you, for example, bold with "fontStyle": "bold":

{width="499"}

You can even experiment with more unusual styles, such as filter: drop-shadow() (it’s more complicated; here’s how the MoonLight theme does it)](https://github.com/robb0wen/synthwave-vscode/blob/ec7e97eba96febbcf069256a6513ecedd0b187ae/README.md)):

{width="501"}

Conclusion

For me, this trick helped a lot in the beginning to better digest TypeScript's new concepts. I could remove this customization now, but I’ve grown used to it and kept it. I hope it helps some of you get started with TypeScript!

Using BroadcastChannel API with Vue to sync a ref across multiple tabs

Nico Prat — Mon, 02 Dec 2024 15:32:48 +0000

We try to save time for everyone in our team, not only developers: some people spend a lot of time configuring our app for clients or demos, so we make sure it's as smooth as possible. For instance, we try to make every change real time, so there's no need to reload the app for changes to appear.

Recently, we figured out those people usually work with multiple tabs open, making sure the configuration works as expected in multiple pages of the app. So we thought about syncing the configuration across tabs.

We didn't want to store it, neither in session, local storage or anything else, as we will then have to make sure it's always up to date.

That's when we came across the BroadcastChannel API, I didn't even know it existed. It's not fairly new, but Safari was the last to implement it according to CanIUse. Anyway it's largely supported now. You can think of it like the good old window.postMessage() from iframe, but across multiple tabs of the same origin.

Luckily for us, VueUse already made a little composable to ease its usage: https://vueuse.org/core/useBroadcastChannel/#usebroadcastchannel

const {
  isSupported,
  channel,
  post,
  close,
  error,
  isClosed,
} = useBroadcastChannel({ name: 'unique-name' })

So we created a little in house composable based on it to make sure a ref is always synchronized among all tabs:

import { useBroadcastChannel, watchPausable } from '@vueuse/core';
import { nextTick, watch } from 'vue';

import type { Ref } from 'vue';

export const useSync = <T>(value: Ref<T>, name: string, options?: { immediate?: boolean; deep?: boolean }) => {
  // Name must be unique
  const { post, data } = useBroadcastChannel<T, T>({ name });

  // When value changes locally, update other tabs
  const { pause, resume } = watchPausable(
    () => value.value,
    (newValue) => {
      post(structuredClone(newValue));
    },
    options,
  );

  // When value changes in another tab, update it locally
  watch(
    () => data.value,
    async (newValue) => {
      // Prevent watch loop when updating config
      pause();
      value.value = newValue;
      await nextTick();
      resume();
    },
    options,
  );
};

So now we can sync a ref with a single line:

const config = ref({})
useSync(config, 'config', { deep: true });

And voilà! That's some hours saved each month across teams 🥳

Incrementally fixing lots of ESlint errors in a clean way with ESlint Nibble

Nico Prat — Mon, 18 Nov 2024 16:10:46 +0000

As our team is growing, we need more functional and aesthetic rules to keep our codebase less error-prone and more consistent. Fortunately, both our backend and frontend use JavaScript (with the same version of TypeScript) so those changes make a big impact on our daily work for the whole team.

We usually do this kind of improvements on what we call "tech days" (on monday every two weeks) when we can work on tasks we choose ourselves. We try to do them incrementally to avoid long lasting branches that are hard to maintain and review.

Recently, we chose to add the Unicorn plugin, which contain dozens of ESlint rules. It can feel overwhelming at first because it triggers hundreds of errors. Fortunately, we discovered eslint-nibble: a command line tool that helps adding rules one by one with a graphical interface.

How to use it

The first step is to install the new plugin we want to apply. Then, instead of enabling the rules one by one, we can now enable them all in .eslintrc.js. Finally, instead of linting everything at once with eslint, we can simply use eslint-nibble like this:

npx eslint-nibble --fixable-only --no-warnings --cache "./src/**/*.{ts,js,vue}"

it speeds up our process at first with --fixable-only rules
since we don't make CI fail on warnings, we use --no-warnings to clear things up
the --cache option is similar to the ESlint one and will make the repeated process much faster

We're then welcomed by a nice graphic that shows every failing rule with the count of errors for each one:

When selecting a rule through its interface, we're proposed to autofix it (if possible). Then, we usually review it manually before committing, just in case something odd pops up.

Another key point is that it's capable of fixing one and only one rule at a time, even if a line a code contains multiple rule errors. It makes the commits atomic, so it's easy to debug and review for instance.

If you make any additional change before committing — for example we sometimes need to apply Prettier on the changed line — make sure you don't save & lint the file, because it would fix all other errors related to other rules in the file. The correct way is to manually fix the needed problem only by focusing the line and running Quick fix , then use the command Fix without formatting of VS Code.

Benefits

The main advantage is to easily see which rules are the simplest to add next. Each day, we can now choose to fix one rule with a lot of errors, or a lot of rules that have only a few occurrences. Previously, we were blindly enabling rules one by one without knowing their impact in advance.

It's also an opportunity to understand the rule itself by reading its documentation and why it's better (or not) to do it this way, so we learn new things.

We sometimes decide to customize or completely disable a rule because it doesn't fit our needs or code style. For instance, we decided to disable a rule forcing to use Set in some cases: as Vue 2 doesn't support reactivity on Map and Set, we thought it could introduce bugs or encourage developers to use it in an unexpected way.

Finally, it's easier for reviewers to read commits about one rule at a time. This tool makes progressive enhancement a breeze by helping us adding a few ESlint rules from time to time.

How we migrated from Vue 2 to Vue 3

Nico Prat — Tue, 12 Nov 2024 13:16:11 +0000

About one year ago we finally migrated from Vue 2 to Vue 3. It was 6 months before its official end of life. At the time, our app has around 100 pages and 300 components, and used some of the classic dependencies tied to Vue: Vue-router, Pinia (and Pinia ORM), Vue-i18n, TipTap, ElementUI (ElementPlus for Vue 3)

Here are a few advices that helped us. As Vue 2 still work pretty well, you better take the time to ease the migration instead of rushing it, breaking your app and destroying your moral!

1️⃣ Before starting

Warn others

Things will certainly break, even a little. You better make sure it's ok with other teams.

Upgrade to latest Vue 2.7

Obviously, as most of the new features are available in Vue 2.7, and retrocompatible, it's important to catch up if you don't already have. While migrating to Vue 3 you'll still be able to enjoy its features. The step to migrate will also be smaller.

Take the time

This can be a pretty big work so you better anticipate to mitigate the risk over a long period. Also, it helped us (the developers) keep the moral! Plan a few weeks or even months, as you know when you start, but you don't know when you'll finish... Finally, it's better to dedicate some time every week, so any outage won't be disastrous.

Create a team

Don't rely on only one developer if possible, as it's an exhausting task. Also, you need quick feedback & merge loops, because a lot of changes will affect the entire codebase and could create conflicts on a daily basis. It's already hard enough without having to handle this!

Test driven migration

Half of the time will be spent testing the whole app, so you better automate it the most possible. In our experience:

Unit tests are not very useful, as they're usually testing things not really tied to Vue (only "pure JS" functions for instance), se we didn't focus on them
Component testing with vue-test-utils were a pain to migrate, in the end we even had to disable some of them
End to end tests were the most valuable as it's not tied to any JS or Vue internals and failed as soon as a error was thrown away in the app

In conclusion the best is to create so-called "smoke test", where you just navigate within the app with the most basic scenario you can think of. Keep them simple, so they're fast, because the sooner you can make them run, so the more useful they'll be. Bonus point if they run before merging (in a CI for instance).

Type everything

TypeScript helped a bit, but support for it in Vue 2 is still poor. Using TypeScript is still a good idea, but it might not help too much there; Once using Vue 3, the setup syntax will be your best friend though!

Lint everything

It's obvious, but a lot of changes will happen in the code, so does a lot of errors. A simple ESLint / Prettier can save a lot of time. If you already do have them, you can check the new rules for Vue 3 meanwhile you migrate: https://eslint.vuejs.org/rules/

Use Vite

We already had migrated from Webpack to Vite before beginning migrating Vue, so I'm not sure it helps a lot, but as it's the clear standard today, some plugins might not even give instruction for upgrade with Webpack. I guess it's safer to do it first as Vite supports Vue 2, but in the opposite the Vue 3 ecosystem might not support Webpack.

2️⃣ Small steps first

The goal is to have the less changes possible when actually upgrading Vue itself.

Upgrade dependencies

Take a look at every Vue-related dependency you use, and check if there's a version that support both Vue 2 and Vue 3, and upgrade to it. Vue-demi helped a lot plugin maintainers to achieve it, so there's a good chance it's available.

For instance, you might want to migrate from Vuex to Pinia, which support both versions (Vuex still requires a small migration) and is the new standard anyway.

Replace dependencies

For other dependencies, you might want to check if any modern alternative could suit your needs. For instance, we replaced vue-mq by vue-use.

Monkeypatch when needed

We had to be pragmatic, so as some migrations were harder than others, we ended up creating a small layer of abstractions to fix it. For instance, we had a hard time with vue-i18n v9 which brings some (sometimes undocumented) breaking changes. So we finally created a helper that expose a custom version of $t to prevent having to rewrite every component (because this most used function now doesn't accept "nullish" values for basically no reason). In other terms, don't be too perfectionist!

3️⃣ Start migrating

Now the hard work begins. Everything we did before will ease the pain. There's no magic here, it will probably be the hardest part of the migration.

Change everything, but nothing

Replace Vue 2 by Vue 3 with the "migration build" (also called compat mode) by following the instructions.

Turn off every available flag so the app runs almost as it did with version 2.

Check that no breaking change is impacting your app, or fix them.

Small steps

Incrementally enable each flag and test the app thoroughly. If some components are too hard to migrate, keep in mind you can override its compatibility option; so you better merge everything but keep a few components to migrate later instead of waiting for the whole app to work right now. Don't try to fix everything at once, let some days pass so you can catch any bugs (and recharge your mental health).

Big steps

Some dependencies don't provide shortcuts though. In our case, migrating our UI library from ElementUI (Vue 2) to ElementPlus (Vue 3) was hard, and couldn't be split into smaller steps. I heard it was even harder for Vuetify. For this, you'll have to be strong, patient, and take time to do it all at once. Maybe allow a full week for it in your team calendar!

Remember that you can still override the compatibility behavior of each component you import at runtime:

import { ElButton } from 'element-plus'

ElButton.compatConfig = {
  FEATURE_ID_A: true // features can also be toggled at component level
}

Last step

Once every flag has been turned on, it's time to remove the migration build. Hopefully you won't discover new unexpected issues by now!

Don't forget to celebrate, you deserved it! 🥳

DEV Community: 365Talents

Things I learned picking up a new language as an adult

The five basic principles

1. Focus on language content that is relevant to you.

2. Use your new language as a tool to communicate.

3. When you first understand the message, you will unconsciously acquire the language.

4. Language learning is physiological training.

5. Psycho-physiological state matters.

The seven actions

1. Listen a lot.

2. Focus on getting the meaning first.

3. Start mixing.

4. Focus on the core.

5. Get yourself a language parent.

6. Copy the face.

7. Directly connect to mental images.

Conclusion

Why do we need async/await in JavaScript?

What problem does it solve?

Node.js has a single-threaded event loop

Callbacks

Promises

async/await

Wrapup

Dates in JS

Terminology

The key takeaway

Timezones

Universal Time Code (UTC)

Storage

DateTime or Instant?

The JS Date class

How to write reviewer-friendly pull requests

1. Write small pull requests

2. Always prioritize readability

3. Create a simple template

4. Explain why it's done in the description

5. Explain how it's done in the files diff

6. Help the reviewer with tips

7. Make a unique commit for renaming or moving files

8. Rebase commits

9. Suggest a pair review if necessary

10. Kill your ego

Automatically take care of outdated browsers thanks to Browserslist and Github Actions

It's all in a regex

Automate the update

Live Coding in Kubernetes: How we debug production data remotely with Tilt

What Tilt does

Our architecture

How we're using it

Advantages

Running code on realistic data

Production similarity

Fewer resources used on laptop

Difficulties

Wrapper script to switch context

Slow cold start

Too many uncontrolled full image rebuilds

Initial friction with Kubernetes

Conclusion

References

Automating GitBook translations with GitHub Actions: A complete guide

Introduction

Defining your requirements

Solution Overview: Automated translation workflow

Step 1: Setting up GitBook with GitSync

Creating a Collection with language Spaces

Configuring GitSync

Repository structure

Step 2: Creating the GitHub Action workflow

Step 3: Implementing the translation script

Step 4: Committing translated content back to the repository

Advanced Customizations

Supporting multiple target languages

Implementing manual review workflows

Optimizing for large content bases

Translation quality considerations

Cost considerations

Conclusion

What we learned by running an accessibility audit of our app

`DateTime` or `Instant`?

The JS `Date` class