Linting ASO Keywords Across Locales — Protecting Apple's 160-Character Search Budget

What the first implementation missed in Japanese

Look closely at that output, though, and one detection is missing.

In the Japanese sample the name is 壁紙アプリ HD and the subtitle is 高画質の背景画像を毎日お届け. The keyword field contains 壁紙 and 高画質, so both are double-indexed. Yet the only thing reported was the repeat of 壁紙 inside the field itself.

The cause is wordsOf(). It splits on whitespace and punctuation, so 壁紙アプリ is treated as a single word and the 壁紙 inside it is never reached. The check works correctly for languages with whitespace word boundaries, and silently passes Japanese and Chinese.

Bugs that only manifest in some languages are among the harder ones to notice, precisely because nothing fails. You come away believing the locale is clean.

The fix was to add a containment check against the concatenated name and subtitle, limited to tokens that contain CJK characters.

  // Japanese and Chinese have no whitespace word boundaries, so token
  // equality misses matches. For those tokens, also test containment
  // against the raw name + subtitle string.
  const CJK = /[\u3040-\u30ff\u3400-\u9fff]/u;
  const indexed = new Set([...wordsOf(meta.name), ...wordsOf(meta.subtitle)]);
  const surface = norm(`${meta.name ?? ''} ${meta.subtitle ?? ''}`);
  const redundant = live.filter((t) => {
    const k = norm(t);
    if (indexed.has(k)) return true;
    return CJK.test(k) && k.length >= 2 && surface.includes(k);
  });

Single-character tokens are excluded to avoid false positives when a common character like 花 happens to appear somewhere in the name. For the same reason containment is restricted to CJK tokens — apply it to English and art starts matching smart.

After the change:

$ node aso-keyword-lint.mjs metadata.sample.json
[NG] ja  indexed 8+14+29 = 51 / 160 chars
     ERROR  keywords: duplicate token(s) 壁紙
     ERROR  keywords: already in name/subtitle 壁紙 / 高画質 / 壁紙 (~10 chars recoverable)
     WARN   keywords: 71 chars unused (71% of budget)

高画質 now surfaces, and ten characters become recoverable in that locale. Out of the twenty-nine characters actually in use, roughly a third was wasted.

This is not a substitute for morphological analysis. Apple has not published how partial matches like 壁紙 versus 壁紙集 are treated in its index, so I treat the check as a way to put suspicious entries in front of a human — not as something that should auto-correct anything.

For how to construct a Japanese keyword field in the first place, Maximizing the App Store keyword field within 100 characters covers separator choices and term selection separately.

Each storefront indexes two locales, not one

Everything so far has treated locales one at a time. Users, though, stand in a country's store — and a single store usually indexes two locales at once.

Japan indexes Japanese alongside English (U.S.). Mainland China indexes Simplified Chinese alongside English (U.K.). The United States indexes English (U.S.) alongside Spanish (Mexico). Each country has its own pair, and if you only ship one half of a pair, the other hundred characters sit unused in that market.

I started paying attention to these pairs while trying to work out why English terms produced nothing in mainland China. The only English locale I shipped was en-US, and that store reads en-GB. Terms cannot rank in a field that does not exist. The cause was not the terms and not the implementation — the field simply was not there.

The second half of this matters just as much: repeating a term inside a pair does not double its weight. The index counts a word once. Putting aesthetic in both en-US and es-MX means one of those ten-character spends buys nothing. Loanwords are where this happens, because when you write Spanish keywords yourself, the terms that already work in English are the ones your hand reaches for.

The same JSON file will tell you where both problems are.

#!/usr/bin/env node
// aso-storefront-lint.mjs — treat the locales a storefront indexes as one pair,
// then report duplicates inside the pair and halves you never shipped.
import { readFileSync } from 'node:fs';
 
// Copy only the countries you actually ship from App Store Connect's
// supported-languages list, and revisit the table once a year.
const STOREFRONTS = {
  US: ['en-US', 'es-MX'],
  JP: ['ja', 'en-US'],
  CN: ['zh-Hans', 'en-GB'],
  DE: ['de-DE', 'en-GB'],
};
 
const LIMIT = 100; // keywords field only
const len = (s) => [...(s ?? '')].length;
const norm = (s) => (s ?? '').normalize('NFKC').toLowerCase().trim();
const tokensOf = (s) => (s ?? '').split(',').map(norm).filter((t) => t !== '');
const CJK = /[぀-ヿ㐀-鿿]/u;
 
function lintPair(locales, data) {
  const present = locales.filter((l) => data[l]);
  const missing = locales.filter((l) => !data[l]);
  const lines = [];
 
  const used = present.reduce((a, l) => a + len(data[l].keywords), 0);
  const budget = locales.length * LIMIT;
  lines.push(`${used} of ${budget} indexed characters in use (${present.join(' + ') || 'none'})`);
 
  for (const l of missing) {
    lines.push(`EMPTY  ${l} not localized (${LIMIT} characters unavailable in this storefront)`);
  }
 
  // Duplicates within the pair, with the same CJK containment check as before
  if (present.length === 2) {
    const [a, b] = present;
    const surfaceB = norm(`${data[b].name ?? ''} ${data[b].subtitle ?? ''} ${data[b].keywords ?? ''}`);
    const setB = new Set(tokensOf(data[b].keywords));
    const dup = tokensOf(data[a].keywords).filter(
      (t) => setB.has(t) || (CJK.test(t) && t.length >= 2 && surfaceB.includes(t)),
    );
    if (dup.length) {
      const saved = dup.reduce((s, t) => s + len(t) + 1, 0);
      lines.push(`DUP    ${a} and ${b} share ${dup.join(' / ')} (counted once; ~${saved} characters recoverable)`);
    }
  }
  return lines;
}
 
const path = process.argv[2];
if (!path) {
  console.error('usage: node aso-storefront-lint.mjs <metadata.json>');
  process.exit(2);
}
const data = JSON.parse(readFileSync(path, 'utf8'));
 
for (const [store, locales] of Object.entries(STOREFRONTS)) {
  const [head, ...rest] = lintPair(locales, data);
  console.log(`[${store}] ${head}`);
  for (const l of rest) console.log(`     ${l}`);
}

The input is the file from the previous section, with the post-comma spaces and duplicate terms cleaned out of en-US and an es-MX block added.

  "en-US": {
    "name": "Beautiful HD Wallpapers",
    "subtitle": "4K backgrounds for your phone",
    "keywords": "aesthetic,live wallpaper,lock screen,nature,minimal"
  },
  "es-MX": {
    "name": "Fondos de Pantalla HD",
    "subtitle": "Imagenes 4K para tu telefono",
    "keywords": "aesthetic,fondos gratis,pantalla de bloqueo,naturaleza,minimal"
  }

$ node aso-storefront-lint.mjs metadata.sample.json
[US] 113 of 200 indexed characters in use (en-US + es-MX)
     DUP    en-US and es-MX share aesthetic / minimal (counted once; ~18 characters recoverable)
[JP] 73 of 200 indexed characters in use (ja + en-US)
[CN] 19 of 200 indexed characters in use (zh-Hans)
     EMPTY  en-GB not localized (100 characters unavailable in this storefront)
[DE] 0 of 200 indexed characters in use (none)
     EMPTY  de-DE not localized (100 characters unavailable in this storefront)
     EMPTY  en-GB not localized (100 characters unavailable in this storefront)

Two loanwords cost eighteen characters in the U.S. pair. Mainland China has an entire hundred-character field sitting empty in a place no amount of polishing the Japanese or U.S. fields can reach. Germany is using none of its two hundred.

A term goes into a pair once. When half a pair is missing, create the field before you choose the terms. Those two rules are what I check when I am unsure whether to add another locale.

One caveat worth stating plainly. Apple does not publish this pairing as an indexing specification. My own table comes from App Store Connect's supported-languages list plus switching the store language and seeing what actually renders. Before adding a country, I look at how my app displays in that store first — slower than assuming, and far faster than being wrong in sixteen locales at once.

When direct translation went nowhere

A linter protects how the budget is spent. What goes into it is a different problem.

When I first took apps multilingual, I translated the English terms that were working and dropped them in. "Live Wallpaper" performed in English, so 动画壁纸 went into Chinese, ライブ壁紙 into Japanese, 라이브 배경화면 into Korean.

Nothing happened. A month later, traffic from those terms had barely moved, and the apps were nowhere in the rankings for them.

The reason became clear later. Users in those markets were not searching for the concept "live wallpaper" at all.

What Chinese users actually searched was 免费壁纸 (free wallpaper) and 高清壁纸 (high-definition wallpaper) — the outcome they wanted, not the technology delivering it. Japanese was the same: 壁紙 無料 and おしゃれ 壁紙 sat far ahead of the feature name ライブ壁紙.

That is when the distinction landed for me. A translation is the name of what we ship. It is not necessarily the name of what someone is looking for. While those two diverge, a perfectly filled keyword field still returns nothing.

Since then I never ship a translation directly. There is always a step in between that asks whether anyone searches that way. Machine translation has improved enormously since, but what improved is fluency — no version of it tells you whether demand exists.

Translation and LLMs are candidate generators, not decision makers

None of which means abandoning translation. It means moving where it sits in the process.

My workflow has three stages.

Stage one widens the pool. I run the working English terms through both DeepL and Google Translate and keep the places where the two disagree. A disagreement usually marks a concept with no settled phrasing in that language, which makes it worth examining. The divergences carry more information than the agreements.

Stage two adds volume. This is where an LLM helps. The prompt does not need to be elaborate.

Suggest 20 long-tail keyword candidates for the Japanese locale of a wallpaper app.
Constraints:
- exclude broad single terms like "wallpaper" on its own
- favor two- and three-word combinations
- separate seasonal candidates from evergreen ones
- for each, add one line describing the situation someone is in when they search it

That last line is the important one. Ask only for terms and you get plausible-looking vocabulary. Ask for the situation behind each term and you can discard the ones where you cannot picture the moment. Adding that single constraint noticeably raised how many suggestions I ended up using.

Stage three throws candidates away. This is the real work. I search each candidate in that locale's store and look at what ranks.

• Apps from an unrelated category rank → the term means something else there. Discard.
• Large publishers own the top → volume exists but there is no way in. Hold.
• Apps of comparable size rank → keep as a candidate.

Neither translation nor an LLM can perform stage three. Both produce phrasings that could be said; neither knows which phrasings are being searched. Confuse the two and you end up with sixteen locales of beautifully translated terms that nobody types. That is precisely what I shipped the first time.

Patterns I have observed by market

After a few years across a dozen-plus locales, some tendencies show up. These come from my own categories — wallpaper and wellness apps — and are observations, not laws. Read them with that caveat.

Price-signaling terms carry weight in some markets. 免费 in Chinese, 無料 in Japanese, 무료 in Korean produced clear movement in my records. "free" works in English too, but the density of competition on that word is different.

Spec-forward terms carry weight in others. In the German, French, and Spanish locales, adding resolution markers like 4K or Ultra HD moved more than descriptive adjectives did.

Some markets are simply less crowded. Arabic and Turkish had far fewer competing apps relative to their speaker base, and short terms could rank. That one caught me off guard.

The risk is freezing these into a per-language answer key and then missing the market shifting underneath. I hold them as hypotheses and still check the current rankings for that locale before deciding anything.

For the sequencing of opening one region at a time, designing Rork multi-region rollout and ASO in order covers the process itself.

Verifying that RTL locales render the way you intended

Right-to-left languages such as Arabic and Urdu carry a category of problem unrelated to word choice.

Paste machine-translated text into App Store Connect, then look at the store page on a device, and punctuation can sit in the wrong place or mixed alphanumeric runs can order differently than intended. The editing field can look correct while the rendered surface does not.

The trailing comma the linter caught arrived through exactly this path. Working in RTL text, it is genuinely hard to see which side a comma attached to, so a stray separator goes unnoticed. Counting it mechanically is more reliable than looking.

For the rendering itself I check in this order.

The third is easy to skip. Name and subtitle truncate in list view, and anything you needed people to read that falls on the truncated side is effectively unread.

The operational side of running many locales lives in notes from running App Store localization for wallpaper apps.

Recording changes so you can actually judge them

Keyword changes do not produce results the moment you ship them. Missing that turns every subsequent judgment sloppy.

I use one spreadsheet. Nothing elaborate.

Filling in the review date in advance is the part that matters. You will check daily for the first few days regardless, and in my experience that early movement is variance rather than signal. Deciding the review date up front keeps those numbers from driving anything.

Always record what you removed. If you only track additions, then when rankings drop and the cause sits on the removal side, there is no path back to it. That cost me about half a year once.

Running parallel versions to compare is possible, but at indie scale the sample is usually too small to read a difference. I settled on changing one thing at a time and waiting two weeks. It feels slower, and it compounds better, because the history stays legible afterward.

Keeping seasonal slots separate from evergreen ones

Categories like wallpaper have pronounced seasonal demand. Nobody looks for cherry blossom wallpapers outside spring — and in spring, reliably, they do.

I split the keyword budget into two kinds of slot ahead of time.

• Evergreen slots: terms with steady year-round traffic — free, high definition, aesthetic
• Seasonal and event slots: terms that stop working once the window closes — cherry blossom, autumn leaves, Christmas, New Year

Deciding in advance how much of the 100 characters is swappable turns each seasonal change into a substitution rather than a redesign. Without that decision you rebuild the field from scratch every time, and eventually stop updating it at all.

Timing runs earlier than feels natural. Review time plus the lag before rankings respond means changing the field during the month in question is already too late. Cherry blossom terms need to be in place during February.

Event slots are shorter still. For a one- or two-week window like Halloween, it is worth asking whether to participate at all. Whether keeping a slot free is worth the overhead depends on how strong the evergreen slots already are. While the evergreen side is still developing, I have had better results leaving seasonal terms alone entirely.

Choosing how broad a term to chase

The other decision worth making early is which weight class of term to target.

Starting out, I went after the highest-volume terms directly — single words like "wallpaper". The top of that field was occupied by large apps, and months passed without appearing in the rankings at all.

What changed things was moving to two- and three-word combinations. "Live Wallpaper Aesthetic" has a fraction of the search volume, and a fraction of the competition with it. Ranking well on a small term produced more traffic than being invisible on a large one.

Put plainly:

What matters is not search volume by itself, but volume × the realistic chance of ranking for it.

The second factor resists quantification, so I judge it by looking at the top ten for that term and asking whether my app would look out of place beside them. Imprecise, but it produces fewer misses than choosing on volume alone.

Once the terms are chosen, placing them within the 160-character budget is a separate task. Name and subtitle are indexed as part of the combination space, so the keyword field only needs the terms that are not already there. Placement errors are exactly what the linter above is detecting.

Where the tooling actually stands

Tooling is the part of ASO writing that goes stale fastest, so it is worth stating the current position.

App Annie, long the default reference, was renamed data.ai around 2021–2022 and was acquired by Sensor Tower in March 2024. The data.ai brand was retired as the platforms merged, and its capabilities now live inside Sensor Tower. Older articles and books that say "look it up in App Annie" are pointing at a name that no longer resolves.

Vendor pricing and plan structures change often enough that any figure printed here would mislead; check the current pages directly. I have walked into a conversation carrying an outdated price in my head, and it did not go well.

Estimated rankings and App Store Connect measurements are different kinds of number. One is modeled, the other is observed. Decisions should rest on the observed side, with estimates reserved for understanding what other publishers are doing. Keeping that separation makes most tooling questions easy.

Once locale count grows, moving metadata into a repository and pushing it through the API is faster in the end. That path is covered in managing store metadata as code with the App Store Connect API. The linter above slots naturally into that pipeline as the verification step.

Deliberately narrowing what you take on first

Everything above assumes sixteen locales, but there is no reason to begin anywhere near that number.

For my first few years I ran three: English, Japanese, and Chinese. With three, I could follow a change through to its outcome and actually read the differences between markets. I added locales only after that reading became reliable.

Starting today, I would pick one of these.

And one thing to do before adding any locale at all: confirm that the locales you already have are actually spending the full 160-character budget.

The Japanese field I opened that spring was using 29 of 100 characters, and 10 of those were duplicates. Scaling that to sixteen locales would have produced sixteen copies of the same hole. I had the order backwards.

What to do next

The most actionable piece here is the linter. The sequence looks like this.

1. Copy name, subtitle, and keywords for every locale of every shipping app into a JSON file
2. Run node aso-keyword-lint.mjs metadata.json and list the locales reporting ERROR
3. Run node aso-storefront-lint.mjs metadata.json and write down the countries where you ship only half a pair
4. Spend the recovered characters — but only on terms already on your candidate list, not new ideas
5. Record the live date and review date, then leave the numbers alone for two weeks

Step four is deliberate. Reorganizing the budget and swapping terms at the same time means that when numbers move, you cannot tell which change did it. Close the holes first, then reconsider the contents. Since adopting that order, my decisions got visibly faster.

Multilingual ASO turned out not to be a language-skill problem. It is a record-keeping and verification problem — at least, framing it that way is what gets me moving.