Titles v2

### For Users

- **Smarter title display** — each series now picks a primary title per language automatically, based on the best available source. No more guessing which title is "the" title.
- **Stacked language flags** — when the same title text applies to multiple languages, flags stack together instead of showing duplicate rows.
- **Language priority** — you can reorder which languages you prefer for title display. Default order: English, Romanized Japanese, Japanese, Romanized Korean.
- **See all titles** — series pages now have a "show all titles" toggle to reveal every known title across all languages.

### For Moderators

- **Title review work zone** — a new `/mod/series/titles` page lets you browse all titles needing attention, filter by issue type (conflicts, low-confidence detections), media type, and language. Each title links to a focused review page with cover art for context.
- **Keyboard-driven review** — resolve titles without touching the mouse. Default shortcuts: `A` approve, `X` reject, `S` skip, `C` change language, `R` set romanized. All shortcuts are customizable and saved to local storage.
- **Conflict resolution** — when multiple metadata sources disagree on a title's text or language, the review page shows all conflicting values with one-click "Use this" buttons. Resolved conflicts auto-reopen if sources change later.
- **Language detection suggestions** — titles with unknown language are automatically analyzed. High-confidence detections are applied instantly; low-confidence ones appear as suggestions you can approve or dismiss.
- **Reworked title editor** — the series edit form now shows source attributions, primary/hidden/manual status, conflict warnings, and detection suggestions inline. Add, edit, hide, unhide, set primary, and delete titles without leaving the page.
- **Submission diff summaries** — title change submissions now show a semantic diff (added/removed/changed) so you can see exactly what a user is proposing before approving.

### For API Users

- **New `titles` field** on series responses — an array of title objects with this shape:

  ```json
  [
   {
    "language": "en",
    "traits": ["official"],
    "title": "Re:Zero -Starting Life in Another World-",
    "note": null,
    "is_primary": true
   },
   {
    "language": "ja",
    "traits": ["native", "official"],
    "title": "\u308a\u305c\u308d\u304b\u3089\u59cb\u3081\u308b\u7570\u4e16\u754c\u751f\u6d3b",
    "note": null,
    "is_primary": true
   },
   {
    "language": "ja-Latn",
    "traits": ["official"],
    "title": "Re:Zero kara Hajimeru Isekai Seikatsu",
    "note": null,
    "is_primary": false
   }
  ]
  ```

- **Deprecation notice** — the old title fields (`title`, `native_title`, `romanized_title`, `secondary_titles`) are deprecated. They still work exactly as before and their behavior is unchanged — but they are now **frozen**. Moderators can no longer edit data through the v1 system; all title management happens through v2. The v1 and v2 fields are independent; changes to v2 titles do not affect v1 fields and vice versa.

Removal of the deprecated fields will happen May 1st - in the meantime, please start migrating to `titles`.

- **Key differences from v1:**
  - `titles` is a flat array of title objects — not keyed by locale like `secondary_titles` was. Every entry has a non-empty `title` string; there are no `null` or empty placeholders. If a language has no title, it simply isn't in the array.
  - `traits` is an array (e.g. `["native", "official"]`), not a single type enum
  - Romanized languages use script codes: `ja-Latn`, `ko-Latn`, `zh-Latn` (replaces the old `-ro` suffix convention)
  - `is_primary` flag indicates the preferred title for each language, this does not make then "official" or "native"

- **Title length limit** increased from 500 to 1,000 characters.

#### Language codes

The `language` field uses [BCP 47](https://www.rfc-editor.org/info/bcp47) language tags. Most codes are plain ISO 639-1 two-letter codes (`en`, `ja`, `ko`, `zh`, `fr`, `de`, ...).

We extend the standard in a few ways:

- **Romanized scripts** use the `-Latn` script subtag per BCP 47: `ja-Latn` (romaji), `ko-Latn` (romanized Korean), `zh-Latn` (pinyin). This replaces the old `-ro` suffix (`ja-ro`, `ko-ro`) from v1.
- **Regional variants** use a lowercased region subtag: `es-la` (Latin American Spanish), `pt-br` (Brazilian Portuguese), `zh-hk` (Hong Kong Chinese).
- **`unknown`** is a special value for titles whose language hasn't been identified yet.

Common codes you'll encounter:

| Code      | Language                    |
| --------- | --------------------------- |
| `en`      | English                     |
| `ja`      | Japanese                    |
| `ja-Latn` | Japanese Romanized (romaji) |
| `ko`      | Korean                      |
| `ko-Latn` | Korean Romanized            |
| `zh`      | Chinese                     |
| `zh-Latn` | Chinese Romanized (pinyin)  |
| `zh-hk`   | Chinese (Hong Kong)         |
| `es-la`   | Spanish (Latin America)     |
| `pt-br`   | Portuguese (Brazil)         |

#### `is_primary`

Each language can have at most one primary title. The `is_primary` flag marks the single best title for that language — it's what the site displays by default.

- There is exactly one `is_primary: true` title per language (enforced by the database).
- Primary titles are elected automatically from metadata sources, but moderators can override the choice manually.
- When picking which title to show, `is_primary` always wins over trait-based ranking. If you only need one title per language, filter by `is_primary: true` and you're done.
- A series will always have at least one primary title across all its languages.

#### Traits

Each title carries one or more traits describing its role:

| Trait         | Meaning                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------- |
| `official`    | The officially licensed or publisher-sanctioned title for that language.                     |
| `native`      | The title in the work's original language and script (e.g. Japanese kanji/kana for a manga). |
| `alternative` | Any other known title — abbreviations, alternate romanizations, cover texts, etc.            |

A single title can have multiple traits. For a more detailed setup of traits, see: https://mangabaka.org/pages/1#title-settings-overview-table

#### Finding the title you want

The simplest approach: filter by `is_primary` and your preferred language.

```js
// Get the primary English title
const en = titles.find((t) => t.is_primary && t.language === 'en')

// Get the primary title in the work's native script
const native = titles.find((t) => t.is_primary && t.traits.includes('native'))
```

If you want to replicate the site's display logic, walk a priority list and pick the first match:

```js
const priority = ['en', 'ja-Latn', 'ja', 'ko-Latn']

function best_title(titles) {
 // Group by language, pick the best in each group
 const best_per_lang = new Map()

 for (const lang of priority) {
  const candidates = titles.filter((t) => t.language === lang)

  if (candidates.length === 0) continue

  // is_primary wins, then official > native > alternative
  candidates.sort((a, b) => score(a) - score(b))
  best_per_lang.set(lang, candidates[0])
 }

 // First language with a match becomes the primary
 for (const lang of priority) {
  if (best_per_lang.has(lang)) return best_per_lang.get(lang).title
 }

 // Fallback: any title
 return titles[0]?.title ?? null
}

function score(t) {
 if (t.is_primary) return 0
 if (t.traits.includes('official')) return 1
 if (t.traits.includes('native')) return 2
 return 3
}
```

the full implementation can be found here

```ts
import type { MediaType, TitleLanguage_v2, TitleLanguagePriority } from '$lib/types/mangabaka'
import { VIRTUAL_LANGUAGE_CODES } from '$lib/types/mangabaka'

/** Input title shape — accepts both TitleInput and SeriesTitleFormEntry */
type TitleInput = {
	language: TitleLanguage_v2
	title: string
	traits: string[]
	is_primary?: boolean
	note?: string | null
}

export type LanguageAttribution = {
	language: TitleLanguage_v2
	traits: string[]
}

export type ResolvedTitle = {
	language: TitleLanguage_v2
	title: string
	traits: string[]
	/** All languages whose best title shares this text (for stacked flag rendering) */
	languages: LanguageAttribution[]
}

export type ResolvedTitles = {
	primary: string
	/** All languages whose best title matches the primary text */
	primary_languages: LanguageAttribution[]
	/** Titles from the user's configured language priority list */
	secondary: ResolvedTitle[]
	/** Titles from languages NOT in the user's priority list */
	other: ResolvedTitle[]
}

/**
 * Internal fallback for callers that don't pass a language_priority option.
 * Used by mod/admin pages and model classes (e.g. resolve_titles(titles) with no options).
 *
 * Uses virtual codes which expand based on context:
 * - With media_type: resolves to the single matching language (e.g. _native → ja for manga)
 * - Without media_type: expands to ALL possible languages (ja, ko, zh, en for _native),
 *   letting the resolution algorithm pick whichever the series has titles for.
 *
 * Matches the user-facing default in ListConfiguration.prefault().
 */
const DEFAULT_LANGUAGE_PRIORITY: TitleLanguagePriority[] = ['en', '_romanized', '_native']

export const RESOLVE_TITLES_FALLBACK = 'unknown title (please report on Discord)'

const FALLBACK_TITLES: ResolvedTitles = {
	primary: RESOLVE_TITLES_FALLBACK,
	primary_languages: [],
	secondary: [],
	other: [],
}

const VIRTUAL_NATIVE_MAP: Record<MediaType, TitleLanguage_v2 | null> = {
	manga: 'ja',
	manhwa: 'ko',
	manhua: 'zh',
	novel: 'ja',
	oel: 'en',
	other: null,
}

const VIRTUAL_ROMANIZED_MAP: Record<MediaType, TitleLanguage_v2 | null> = {
	manga: 'ja-Latn',
	manhwa: 'ko-Latn',
	manhua: 'zh-Latn',
	novel: 'ja-Latn',
	oel: null,
	other: null,
}

// All unique non-null values from each virtual map, used as fallback when media_type is unknown
const VIRTUAL_NATIVE_ALL: TitleLanguage_v2[] = [
	...new Set(Object.values(VIRTUAL_NATIVE_MAP).filter((v): v is TitleLanguage_v2 => v !== null)),
]
const VIRTUAL_ROMANIZED_ALL: TitleLanguage_v2[] = [
	...new Set(Object.values(VIRTUAL_ROMANIZED_MAP).filter((v): v is TitleLanguage_v2 => v !== null)),
]

/**
 * Expand virtual language codes (_native, _romanized) into real language codes
 * based on the series media type. Deduplicates against codes already in the list.
 *
 * When media_type is provided, each virtual code resolves to the single matching language.
 * When media_type is absent, each virtual code expands to ALL possible languages it could
 * resolve to (ja, ko, zh, en for _native; ja-Latn, ko-Latn, zh-Latn for _romanized),
 * letting the resolution algorithm pick whichever the series has titles for.
 */
function expand_virtual_languages(priority: TitleLanguagePriority[], media_type?: MediaType): TitleLanguage_v2[] {
	const result: TitleLanguage_v2[] = []
	const seen = new Set<TitleLanguage_v2>()

	for (const code of priority) {
		if (!VIRTUAL_LANGUAGE_CODES.has(code)) {
			const real = code as TitleLanguage_v2

			if (!seen.has(real)) {
				seen.add(real)
				result.push(real)
			}

			continue
		}

		if (media_type) {
			const map = code === '_native' ? VIRTUAL_NATIVE_MAP : VIRTUAL_ROMANIZED_MAP
			const resolved = map[media_type]

			if (resolved && !seen.has(resolved)) {
				seen.add(resolved)
				result.push(resolved)
			}
		} else {
			const all = code === '_native' ? VIRTUAL_NATIVE_ALL : VIRTUAL_ROMANIZED_ALL

			for (const lang of all) {
				if (!seen.has(lang)) {
					seen.add(lang)
					result.push(lang)
				}
			}
		}
	}

	return result
}

/**
 * Sort score for a title within a language group.
 * Lower score = higher priority.
 */
function sort_score(t: TitleInput): number {
	if (t.is_primary) return 0
	if (t.traits.includes('official')) return 1
	if (t.traits.includes('native')) return 2
	if (t.traits.includes('alternative')) return 3

	return 4
}

function best_in_group(titles: TitleInput[]): TitleInput | undefined {
	if (titles.length === 0) return undefined

	let best = titles[0]
	let best_score = sort_score(best)

	for (let i = 1; i < titles.length; i++) {
		const score = sort_score(titles[i])

		if (score < best_score) {
			best = titles[i]
			best_score = score
		}
	}

	return best
}

/**
 * Resolve titles from a v2 titles array into a primary + ordered secondary lists.
 *
 * Instead of deduplicating identical title text, groups languages that share the same
 * best title into stacked language attributions (like stacked source favicons on ratings).
 *
 * Primary: the best title found by walking language_priority groups, then native-trait titles, then any title.
 * primary_languages: all languages whose best title matches the primary text.
 * Secondary: grouped titles from priority languages with different text than primary.
 * Other: grouped titles from non-priority languages with different text than primary.
 */
export function resolve_titles(
	titles: TitleInput[] | null | undefined,
	options?: { language_priority?: TitleLanguagePriority[]; media_type?: MediaType },
): ResolvedTitles {
	if (!titles || titles.length === 0) {
		return FALLBACK_TITLES
	}

	const raw_priority = options?.language_priority ?? DEFAULT_LANGUAGE_PRIORITY
	const priority = expand_virtual_languages(raw_priority, options?.media_type)
	const priority_set = new Set(priority)

	// Step 1: Find the best title per language
	const titles_by_lang = new Map<TitleLanguage_v2, TitleInput[]>()

	for (const t of titles) {
		const group = titles_by_lang.get(t.language)

		if (group) {
			group.push(t)
		} else {
			titles_by_lang.set(t.language, [t])
		}
	}

	const best_per_lang = new Map<TitleLanguage_v2, TitleInput>()

	for (const [lang, group] of titles_by_lang) {
		const best = best_in_group(group)

		if (best) {
			best_per_lang.set(lang, best)
		}
	}

	// Step 2: Find primary title text by walking priority
	let primary_title: TitleInput | undefined

	for (const lang of priority) {
		const best = best_per_lang.get(lang)

		if (best) {
			primary_title = best
			break
		}
	}

	// Fallback: titles with 'native' trait
	if (!primary_title) {
		const native_group = titles.filter((t) => t.traits.includes('native'))
		primary_title = best_in_group(native_group)
	}

	// Fallback: any title
	if (!primary_title) {
		primary_title = best_in_group(titles)
	}

	if (!primary_title) {
		return FALLBACK_TITLES
	}

	const primary_str = primary_title.title

	// Step 3: Group best-per-lang entries by title text
	const text_groups = new Map<string, LanguageAttribution[]>()

	for (const [lang, best] of best_per_lang) {
		const existing = text_groups.get(best.title) || []
		existing.push({ language: lang, traits: best.traits })
		text_groups.set(best.title, existing)
	}

	// Step 4: Sort languages within each group by priority order
	const priority_index = new Map<TitleLanguage_v2, number>()

	for (let i = 0; i < priority.length; i++) {
		priority_index.set(priority[i], i)
	}

	const sort_by_priority = (a: LanguageAttribution, b: LanguageAttribution) => {
		const a_idx = priority_index.get(a.language) ?? priority.length
		const b_idx = priority_index.get(b.language) ?? priority.length

		return a_idx - b_idx
	}

	// Step 5: Build primary_languages
	const primary_languages = text_groups.get(primary_str) || [
		{ language: primary_title.language, traits: primary_title.traits },
	]

	primary_languages.sort(sort_by_priority)

	// Step 6: Build secondary and other from remaining text groups
	const secondary: ResolvedTitle[] = []
	const other: ResolvedTitle[] = []

	for (const [text, langs] of text_groups) {
		if (text === primary_str) continue

		langs.sort(sort_by_priority)

		const entry: ResolvedTitle = {
			title: text,
			language: langs[0].language,
			traits: langs[0].traits,
			languages: langs,
		}

		if (langs.some((l) => priority_set.has(l.language))) {
			secondary.push(entry)
		} else {
			other.push(entry)
		}
	}

	// Sort secondary by priority order of first language in each group
	secondary.sort((a, b) => {
		const a_idx = priority_index.get(a.language) ?? priority.length
		const b_idx = priority_index.get(b.language) ?? priority.length

		return a_idx - b_idx
	})

	return {
		primary: primary_str,
		primary_languages,
		secondary,
		other,
	}
}
```