
Yesterday, I posted about [implementing i18n routing in a nextjs project](/garden/12-i18n-nextjs), focusing on the `app` folder and middleware setup. This post follows from that post with an `I18NLink` component that leverages our i18n set up to automatically prefix your links with the user's current language. This way, you can do something like this:

``` typescript
<I18NLink href="/settings">{t('settings', 'Settings')}</I18NLink>
```

And the link will automatically pick up the `lang` param to route to either `/settings` or (for example) `/es/settings` depending on the `lang` in the url.

Note: the `t` function is a stand in for a generic translation function that would take a key like `settings` and return a string or fallback to the second argument, which is "Settings".

## wrapping the `Link` component

The first thing we need to do is wrap NextJS's default `Link` component:

``` typescript
import type { ComponentProps } from 'react';
import React from 'react';
import Link from 'next/link';

export type I18NLinkType = Omit<ComponentProps<typeof Link>, 'as'> & {
  href: string;
};

function I18NLink({ children, href, ...props }: I18NLinkType) {
  return (
    <Link href={href} {...props}>
      {children}
    </Link>
  )
}
```

A few things are happening here:

1. We are creating a new `I18NLinkType` by taking the `Link` type and omitting `as` so we can use the component polymorphically.
2. We are defining `href` as a string since `Link` potentially accepts a `URL`.
3. We then create a function that's more or less a pass-through: take the `href` and `children` and just pass them to `Link`.

This isn't doing too much yet. We need to hook it into the `useParams` hook.

## get current `lang` param

Let's update the component:

``` typescript
import { useParams } from 'next/navigation';

// generic import of your default language
import { defaultLanguage } from 'settings';

function I18NLink({ children, href, ...props }: I18NLinkType) {
  const params = useParams();
  const currentLanguage = (params?.lang as string) || defaultLanguage;

  return (
    <Link href={`${currentLanguage}${href}`} {...props}>
      {children}
    </Link>
  )
}
```

Note that `params` could be `null` or an empty `Record`, so we want to coerce `lang` as a string.

This isn't a bad solution, but we're going to run into a few problems:

1. We don't want to prepend the `defaultLanguage` if we don't have to since it'll cause an extra redirect in the middleware.
2. We can't use the Link generically since it'll only work for relative paths. If we pass an absolute or external route, the url will be malformed.

## checking incoming href

What we need to do to prevent the above is check the incoming `href` and make decisions about what `href` to actually pass to `Link`.

``` typescript
function getPath(path?: string | null) {
  // 1.
  if (!path) {
    return ['en', ''];
  }

  // 2.
  const pathArray = path.split('/').filter((x) => !!x);

  // 3. empty array
  if (pathArray.length === 0) {
    return ['en', ''];
  }

  // 4.
  const [lang, ...restPath] = pathArray;

  // 5.
  if (languageArray.includes(lang)) {
    return [lang, restPath.join('/')];
  }

  // 6.
  return ['en', pathArray.join('/')];
}


function getPrefixedUrl(href: string, currentLanguage: string) {
  // 1. handle absolute links
  if (/^((http|https):\/\/)/.test(href)) {
    return href;
  }

  // 2.
  const [, tail] = getPath(href);

  // 3.
  if (currentLanguage === defaultLanguage) {
    return `/${tail}`;
  }

  // 4.
  return `/${currentLanguage}/${tail}`;
}
```

Let's start with `getPrefixedUrl`:

1. If the `href` starts with `http` or `https`, we should follow the absolute route provided.
2. Otherwise, we want to get the url path without the `lang` param if it's provided.
3. If the `currentLanguage` is also the default language, just pass the `tail` of the path
4. Otherwise, prepend the current language to the `tail` of the path

`getPath` might seem a little extraneous or verbose, but it's meant to help avoid issues with passing around the root and with overriding the `lang` provided in the url.

1. If the `path` is null, return an array we can use to route the user to the root of the site.
2. Take the path, and split it at `/`. The array is going to be easier to work with.
3. If the array is empty because `path === '/'`, return an array we can use to route the user to the root of the site. 
4. We want to deal with just `restPath` if (and only if) the first part of the url is actually an `lang` param.
5. We do a check to ensure that `lang` is include in our `langaugeArray`, which tells us we can safely use `restPath`
6. Otherwise we want to return the whole path we were provided

With these helper functions, we can update the component:

``` typescript
function I18NLink({ children, href, ...props }: I18NLinkType) {
  const params = useParams();
  const currentLanguage = (params?.lang as string) || defaultLanguage;
  const prefixedHref = getPrefixedUrl(href, currentLanguage);
  return (
    <Link href={prefixedHref} {...props}>
      {children}
    </Link>
  )
}
```

### bonus: anchor or `Link`

If you want to escape the client cache with a "hard" route, you might want to be able to use *either* an anchor or `Link` component:

``` typescript
export type I18NLinkType = Omit<ComponentProps<typeof Link>, 'as'> & {
  isAnchor?: boolean;
  href: string;
};

function I18NLink({ children, href, isAnchor, ...props }: I18NLinkType) {
  const params = useParams();
  const currentLanguage = (params?.lang as string) || defaultLanguage;
  const prefixedHref = getPrefixedUrl(href, currentLanguage);
  if (isAnchor) {
    return (
      <a href={prefixedHref} {...props}>
        {children}
      </a>
    );
  }

  return (
    <Link href={prefixedHref} {...props}>
      {children}
    </Link>
  )
}
```

We can just use a `boolean` and render an anchor tag based on `isAnchor` if passed.

## wrapping up

It would be great to have a more built in way to handle internationalization in NextJS, however it only requires a little bit of boilerplate to get a full fledged i18n setup, including automatic i18n routing with NextJS's default `Link` component.

Check out the full gist [here](https://gist.github.com/inadeqtfuturs/5281c16d825208fb36fec0ecb79d4d65).


i18n routing with nextjs 13 app router

automatic i18n linking with nextjs 13 app router


Recently at [graveflex](https://graveflex.com), I created a learning platform for one of our clients. In addition to mutli-tenant authentication and authorization, the whole platform needed to be translatable. Having done a handful of i18n sites in the past using [NextJS's pages router](https://nextjs.org/docs/pages/building-your-application/routing/internationalization), I was surprised to find how minimal the [app router] documentation was, largely leaving the complexity of routing to external packages.

Initially, I assumed that I could use one of these external packages to handle routing, but I ran into a few problems with each:

- [next-intl](https://next-intl-docs.vercel.app/docs/getting-started/app-router-server-components): needed more control inside middleware and didn't want to opt into what seemed like a fairly complex boilerplate set up they provide for `Auth.js`.
- [next-international](https://next-international.vercel.app/docs/app-setup): similar to `next-intl`, but we also didn't have the need to manage transations in the same way given our data structure and CMS.
- [next-i18n-router](https://github.com/i18nexus/next-i18n-router/): same concern about middleware, though, of all the solutions NextJS links out to, this one seems the like the most streamlined.

It seemed like it might just be easiest and that we could maintain the most control if we rolled out our own middleware. What we wanted was to define a set of potential locales (English and Spanish), and define one as the default locale. When the user was routing using the default locale, we didn't want the locale param to be displayed to the end user, however, the locale params *should* display when routing in any locale that is not the default.

``` javascript
`/` -> home
`/es` -> home translated
`/some-route` -> settings
`/es/settings` -> settings translated
```

The process of setting up the routing required two things: first, we need to wrap all routes inside the `app` folder in `[lang]` (or any dynamic route), and then set up the middleware to handle rewrites and redirects. The middleware needed to do the following:

1. check if there is a locale in the path
2. if there's no locale, we assume it's the default locale. however, *rewrite* the path to include the default locale so we have access to it from `useParams()`
3. if the locale is the default locale, redirect without the locale so the user doesn't see it in the url
4. if the locale is not valid, redirect the path with the default locale
5. otherwise, the locale is valid and the request should just pass through the middleware

While the above is opinionated, it defines, in general, how all of packages listed above work. Additionally, writing the middleware alerted us to handful of problems we might have run into otherwise.

## `app` set up

Following the conventions of i18n packages and NextJS's docs, we started by wrapping the entire file structure in the `app` folder in `[lang]`.

``` javascript
└── app/[lang]/
    ├── (public)
    │   ├── layout.tsx
    │   └── login/
    │       ├── LoginPage.tsx
    │       └── page.tsx
    └── (user)
        ├── layout.tsx
        ├── not-found.tsx
        ├── page.tsx
        ├── [...not-found]/
        │   └── page.tsx
        └── settings/
            ├── page.tsx
            └── layout.tsx
```

> Note: this is an overly simplified file structure to explain how the routing works.

There are a handful of things that happen when you set the routing up this way:

1. Because every route is nested under `[lang]`, you will always have access to the `lang` param either as a parameter in server components like `layout` or `page`, as well as `useParams`.
2. Defining [route groups](https://nextjs.org/docs/app/building-your-application/routing/route-groups) as `(public)` and `(user)` allows us to separate the layouts, pages, and general data fetching we're doing for either authenticated or unauthenticated users.
3. Note the [catch-all segment](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes#catch-all-segments) in the `(user)` folder -- this is a file that just returns `notFound()` so that we can (1) translate the not found page and (2) correctly display that page within the authenticated navigation shell.

## middleware set up

Knowing how we want the middleware to behave, we can break the function down into a few steps:

### set language config

First, we set up some constants to reference throughout the middleware.

``` javascript
const languages = ['en', 'es'];
const defaultLanguage = 'en'
```

### check for locale in path

``` javascript
import type { NextRequest } from 'next/server'

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const matches = pathname.match('^/([a-z]{2})(/.*)?$');
  const language = !matches ? 'en' : matches[1];
}
```

Inside the actual middleware function, we grab the `pathname` from the request and run it against a regex pattern that's looking for `/xx/` as the first part of the pathname. If you needed language and locale support, you could rewrite the regex to suit those needs. Otherwise, we set `langauge` to be either the default language, or the language passed in the path.

### handle no locale

``` javascript
export async function middleware(request: NextRequest) {
  // ...previous code

  // no locale -- assume en and rewrite so nextjs gets lang params
  // but user sees url without language
  if (!matches) {
    // note `newURL` 
    return NextResponse.rewrite(newURL(`/${defaultLanguage}${pathname}`, request));
  }
}
```

When there is no locale, we *rewrite* the request so that NextJS sees locale included in the URL, while the user does NOT see the locale in the URL.

Note the `newURL` function: we can't just pass the pathname because we're lose other parts of the url path. We knew we wanted to maintain (at the least) the query string params, so we wrote a function to pass those along:

``` javascript
// construct new url based on desired path and original request
function newURL(url: string, originalRequest: NextRequest) {
  const originalUrl = originalRequest.url;
  const query = originalRequest.nextUrl.searchParams.toString();

  const nextUrl = query ? `${url}?${query}` : url;

  return new URL(nextUrl, originalUrl);
}
```

### redirect if default locale is included

``` javascript
export async function middleware(request: NextRequest) {
  // ...previous code
  // redirect if defaultLanguage === language
  if (language === defaultLanguage) {
    return NextResponse.redirect(
      newURL(
        pathname.replace(`/${defaultLanguage}`, '/').replace('//', '/'),
        request
      )
    );
  }
}
```

If the `language` matches the `defaultLanguage`, we want to remove the language from the url so it can be handled by the rewrite.

### handle invalid language

``` javascript
export async function middleware(request: NextRequest) {
  // ...previous code
  const invalidLanguage = !languages.includes(languageFromPath);
  if (invalidLanguage) {
    return NextResponse.redirect(newURL(`/${defaultLanguage}${currPath}`, request));
  }

}
```

If the language we got from the path is not invluded in our languages array, route to the path but relative to the default language to either `200` throw a `404`.


### allow passthrough

If we have a valid language, we can just pass the request through.

``` javascript
export async function middleware(request: NextRequest) {
  // ...previous code
  return NextResponse.next();
}
```

### clean up

One thing you might notice is that we're not taking advantage of headers to pass the language around in requests. The main reason for this is simplicity and visibility: we don't want to obfuscate the user preferred language in a header when we can just have it as part of the URL.

However, we could (and should) leverage the browser's built-in language handling. To do this, we can wrap our responses in a helper function:

``` javascript
function addLanguageRespHeader(resp: NextResponse, lang: string = 'en') {
  resp.headers.set('Content-Language', lang);

  return resp;
}
```

Just pass along the `lang` as the second argument to set the header value:

``` javascript
  // ex.
  return addLanguageRespHeader(NextResponse.next(), languageFromPath);
```

## wrapping up

It might seem like a lot, but we can break the functionality of our middleware down to a few explicit steps and write the code ourselves. In the future, we'll probably package this along with instructions for composing it with other middleware.


garden monorepo


Documentation takes many forms. Often we talk about documentation within our code, like inline comments describing or annotating a function or piece of code. We also talk about tests and specs as a kind of documentation, where tests provide a source of truth for a function's input and result. I see this kind of documentation as tied up in and with the codebase. It's there for the developer, but, more often than not, it's actually "there" for a language server protocol (inline comments) or a CI/CD pipeline (test suite) to ensure that the code is doing what it's supposed to do. This kind of documentation is extremely important and makes working in a codebase much easier, but it's not the only documentation we need.

Documentation for human readers does and should take a different form because human readers are neither lsps or CI/CD pipelines. Sometimes we need to create documentation about how our codebase interacts with an external system or saas. Ideally there is infra-as-code, but often we just need a reminder of what buttons to click in a CMS somewhere. Other times, a codebase has unique internal procedures and systems that need to be described in order to be used. In each case, we need documentation that provides a conceptual as well as practical overview.

The kind of documentation I'm thinking about is harder to write than documentation in and as code because it's not tied into a system of 1:1 input/output. It might seem obvious that two people reading the same document will not get the same thing out of it, but we also want to cultivate strategies, systems, and templates that make it likely that anyone with some amount of technical understanding (your peers) could read the documentation and understand it.

However, in trying to outline some parameters for creating internal documentation for other developers on my current team, I found external resources lacking. Most writing about documentation emphasizes one of two things: how *code* should be documented (either within docs as code blocks or within the codebase itself with comments and spec) OR tools that teams can use to create documentation. In both cases, the emphasis misses the actual form documentation takes either by narrowly focusing on code or too broadly gesturing towards a metaframework to help with organization. The question I wanted to answer was, "What does the writing look like for internal documentation?"

Articles about documentation often focus on writing opensource documentation. However, opensource docs are geared towards the user of a product, rather than someone that is actively working on the product. While some contribution guidelines model the kind of writing I was thinking about, not many have written publicly about creating documentation for an internal team.

Additionally, the writing I did find about documentation tended to be vague on how to best to structure docs. This made some sense: the structure documentation takes depends largely on what you're documenting, the project you're working on, and even who and how many pepople are working on it. However, what I was finding was that different developers on my team were writing radically different kinds of documentation formally, grammatically, structurally, etc. What I wanted was something to guide their thinking so that we were all contributing the same *kind* of documentation.

Inspired by the idea of an [opionated framework](https://opinionatedreact.com/)[^1], I've started writing an "opionated guide to internal documentation". This is geared at standardizing the way documenation is written within a team, the goal being the creation of documentation that likely communicates, explains, or otherwise transfers knowledge between team members.

You can find it below or linked [here](https://gist.github.com/inadeqtfuturs/46466d91ce9ea048c87172631c5ed8c3).[^2]

This is an in progress document and is meant to be opionated rather than authoritative.

```markdown
---
title: opinionated documentation
---

# Opinionated Documentation

This guide outlines some principles for writing internal documentation. The scope of this guide is narrow and is adapatable depending on the project and team size.

## Consider the reader

The reader is most often going to be another developer. Because of that, we can assume some level of familiarity with the code base, language/framework, or service we're writing documentation for. Consider some of the following when writing:

- Opt for explicit instructions rather than implicit. I.e. tell the reader exactly what to code. Tell them what to click in the service you're writing about.
- Provide copy and paste-able code blocks.
- Explicitly reference files that need to be updated or that stand as an example of what is being documented.
- Docs should be skimmable/scannable, so opt for descriptive headings and clear topic/introductory sentences.
- File names and topics should be easy to find by looking at file names and/or `grep`ing the docs folder.

## Write Consistently

The documentation should be consistent with the rest of the documentation in the repo. That is, it should follow a similar format (see below) and voice of other pieces of documentation. Just as we have a consistent code style within the repo, we should have a consistent documentation style within the repo.

In general, write with a neutral tone and/or the tone consistent with the documentation in the repo.

## Instruction vs. Explanation

Docs can take two (of many) shapes: instructive and explanatory. Instructive docs tell a dev what to do to implement a feature, like adding a new slice to redux. Explanatory docs explain why a codebase, process, file, or function is written or how it works. Docs are often a combination of the two, but it's usually best to separate instuctions from explanations.

In the following example, we provide a few things:

1. A brief overview of the feature/thing we're talking about
2. Explicit step-by-step instructions for implementing/working with the thing
3. An explanation of *why* we've opted to do it this way
4. (Optional) A list of resources related to the thing if the reader is unfamiliar

### Example

\``` markdown
# Topic

## Subtopic

Brief explanation of what subtopic is

1. Instructions
2. For implementing
3. Subtopic

Brief explanation of why we've decided to implement feature or whatever this way.

## Resources

- [Resource](link)
- [Resource](link)
- [Resource](link)
\```

## Breaking Down a Topic

Depending on what you're documenting or the size of the codebase, a flat list of markdown files might not be the best form for documentation. Consider the following:

- Are you documenting something isolated and singular, or something that's part of a larger system? A folder might house multiple pieces of documentation about a system or a topic that has many discrete parts. An example might be a "State Management" folder with separate files for things like reducers, actions, hooks, and how the codebase tends to structure state.
- When a single file gets too long (hundreds of lines), it might be time to rethink its structure and break it into multiple files. The headings in the original file are helpful for creating the new files.
- Use relative links to link between documents.

## Formatting

- Use properly formatted markdown.
- Provide a semantic and skimmable hierarchy of information by using headings.
- Use lists for instructions. Numbered lists are good for sequences, whereas unordered lists are good for general tips/suggestions.  
- Add a single white space between semantic elements in the markdown.

## Resources

- [Write the Docs - Documentation Principles](https://www.writethedocs.org/guide/writing/docs-principles/#arid)
- [Write the Docs - Introduction to Markdown](https://www.writethedocs.org/guide/writing/markdown/)

```

[^1]: I see turning to an opionated framework as trusting someone else's expertise. It also decreases friction by decreasing the amount of decisions that *you* have to make in order to get a project up and running or write a piece of code. It's why we have styleguides, linting, and other guardrails when we code.
[^2]: Note to create a little code block that just shows the live raw of the gist. For another day.
