@jjlmoya/utils-finance 1.46.0 → 1.47.0

package/src/tool/loanAprScenarioCalculator/dom-views.ts

@@ -0,0 +1,190 @@
+import type { LoanAprScenarioCalculatorUI } from "./ui";
+import type { ComparisonResult, LoanScenarioResult } from "./logic";
+import { currencyFormatLocale, type LoanAprCurrencyCode } from "./currency";
+import { getDifferenceLabel, getScenarioBadge } from "./evaluator";
+
+function money(
+  value: number,
+  locale: string,
+  currency: LoanAprCurrencyCode,
+): string {
+  return new Intl.NumberFormat(currencyFormatLocale[currency] ?? locale, {
+    style: "currency",
+    currency,
+    maximumFractionDigits: 2,
+  }).format(value);
+}
+
+function percent(value: number): string {
+  return `${value.toFixed(2)}%`;
+}
+
+function escapeText(value: string): string {
+  return value.replace(
+    /[&<>"']/g,
+    (character) =>
+      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[
+        character
+      ] ?? character,
+  );
+}
+
+type MetricTone = "better" | "worse" | "neutral" | "";
+
+function metric(
+  label: string,
+  value: string,
+  emphasis = false,
+  tone: MetricTone = "",
+): string {
+  const classes = [
+    "loan-apr-metric",
+    emphasis ? "loan-apr-metric-emphasis" : "",
+    tone ? `loan-apr-metric-${tone}` : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return `<div class="${classes}"><dt>${escapeText(label)}</dt><dd>${escapeText(value)}</dd></div>`;
+}
+
+function timeline(input: {
+  result: LoanScenarioResult;
+  side: "a" | "b";
+  ui: LoanAprScenarioCalculatorUI;
+  locale: string;
+  currency: LoanAprCurrencyCode;
+}): string {
+  const { result, side, ui, locale, currency } = input;
+  const firstPayment = money(
+    result.monthlyPayment + result.monthlyFees,
+    locale,
+    currency,
+  );
+  const finalPayment = money(
+    result.monthlyPayment + result.monthlyFees + result.finalFees,
+    locale,
+    currency,
+  );
+  return `<div class="loan-apr-timeline loan-apr-timeline-${side}" aria-label="${escapeText(result.name)} ${escapeText(ui.labelTimeline)}"><div class="loan-apr-timeline-track"><span class="loan-apr-timeline-dot loan-apr-timeline-start"></span><span class="loan-apr-timeline-line"></span><span class="loan-apr-timeline-dot loan-apr-timeline-end"></span></div><div class="loan-apr-timeline-labels"><span>${escapeText(ui.labelStart)}<strong>${escapeText(money(result.netCashReceived, locale, currency))}</strong></span><span>${escapeText(ui.labelMonthly)}<strong>${escapeText(firstPayment)}</strong></span><span>${escapeText(ui.labelEnd)}<strong>${escapeText(finalPayment)}</strong></span></div></div>`;
+}
+
+function errorMessage(
+  error: string | undefined,
+  ui: LoanAprScenarioCalculatorUI,
+): string {
+  if (error === "principal") return ui.labelInvalidPrincipal;
+  if (error === "term") return ui.labelInvalidTerm;
+  if (error === "fees") return ui.labelInvalidFees;
+  if (error === "rate") return ui.labelInvalidRate;
+  return ui.labelInvalidPayment;
+}
+
+interface ViewContext {
+  ui: LoanAprScenarioCalculatorUI;
+  locale: string;
+  currency: LoanAprCurrencyCode;
+}
+
+function badgeText(
+  badge: ReturnType<typeof getScenarioBadge>,
+  ui: LoanAprScenarioCalculatorUI,
+): string {
+  if (badge === "lower") return ui.labelLowerCost;
+  if (badge === "higher") return ui.labelHigherCost;
+  if (badge === "neutral") return ui.labelTie;
+  return ui.labelNeedValidInputs;
+}
+
+function metricTone(
+  current: number,
+  other: number,
+  higherIsBetter = false,
+): MetricTone {
+  if (!Number.isFinite(current) || !Number.isFinite(other)) return "";
+  if (Math.abs(current - other) < 0.005) return "neutral";
+  const currentIsBetter = higherIsBetter ? current > other : current < other;
+  return currentIsBetter ? "better" : "worse";
+}
+
+function visualComparison(
+  first: LoanScenarioResult,
+  second: LoanScenarioResult,
+  comparison: ComparisonResult,
+  ui: LoanAprScenarioCalculatorUI,
+): string {
+  const firstBadge = getScenarioBadge("a", first, comparison);
+  const secondBadge = getScenarioBadge("b", second, comparison);
+  const aprValue = (result: LoanScenarioResult): string =>
+    result.valid ? percent(result.effectiveApr) : "-";
+  return `<div class="loan-apr-visual-comparison" aria-label="${escapeText(ui.labelEffectiveApr)}"><div class="loan-apr-visual-side loan-apr-visual-${firstBadge}"><span class="loan-apr-visual-index">A</span><span class="loan-apr-visual-name">${escapeText(first.name)}</span><strong>${escapeText(aprValue(first))}</strong><small>${escapeText(badgeText(firstBadge, ui))}</small></div><div class="loan-apr-visual-vs" aria-hidden="true">VS</div><div class="loan-apr-visual-side loan-apr-visual-${secondBadge}"><span class="loan-apr-visual-index">B</span><span class="loan-apr-visual-name">${escapeText(second.name)}</span><strong>${escapeText(aprValue(second))}</strong><small>${escapeText(badgeText(secondBadge, ui))}</small></div></div>`;
+}
+
+function scenarioPanel(input: {
+  result: LoanScenarioResult;
+  other: LoanScenarioResult;
+  side: "a" | "b";
+  comparison: ComparisonResult;
+  context: ViewContext;
+}): string {
+  const { result, other, side, comparison, context } = input;
+  const { ui, locale, currency } = context;
+  const badge = getScenarioBadge(side, result, comparison);
+  const statusText = badgeText(badge, ui);
+  if (!result.valid)
+    return `<article class="loan-apr-result-panel loan-apr-result-invalid"><header><span class="loan-apr-result-index">${side.toUpperCase()}</span><h3>${escapeText(result.name)}</h3><span class="loan-apr-badge loan-apr-badge-invalid">${escapeText(statusText)}</span></header><p>${escapeText(errorMessage(result.error, ui))}</p></article>`;
+  return `<article class="loan-apr-result-panel loan-apr-result-${badge}"><header><span class="loan-apr-result-index">${side.toUpperCase()}</span><h3>${escapeText(result.name)}</h3><span class="loan-apr-badge">${escapeText(statusText)}</span></header>${timeline({ result, side, ui, locale, currency })}<dl class="loan-apr-metrics">${metric(ui.labelEffectiveApr, percent(result.effectiveApr), true, metricTone(result.effectiveApr, other.effectiveApr))}${metric(ui.labelMonthlyPaymentResult, money(result.monthlyPayment, locale, currency), false, metricTone(result.monthlyPayment, other.monthlyPayment))}${metric(ui.labelTotalPaid, money(result.totalPaid, locale, currency), false, metricTone(result.totalPaid, other.totalPaid))}${metric(ui.labelTotalFees, money(result.totalFees, locale, currency), false, metricTone(result.totalFees, other.totalFees))}${metric(ui.labelFinanceCost, money(result.financeCost, locale, currency), false, metricTone(result.financeCost, other.financeCost))}${metric(ui.labelNetCashReceived, money(result.netCashReceived, locale, currency), false, metricTone(result.netCashReceived, other.netCashReceived, true))}</dl></article>`;
+}
+
+function winnerText(
+  first: LoanScenarioResult,
+  second: LoanScenarioResult,
+  comparison: ComparisonResult,
+  ui: LoanAprScenarioCalculatorUI,
+): string {
+  if (comparison.winner === "a")
+    return `${first.name} ${ui.labelLowerCost.toLowerCase()}`;
+  if (comparison.winner === "b")
+    return `${second.name} ${ui.labelLowerCost.toLowerCase()}`;
+  if (comparison.winner === "tie") return ui.labelTie;
+  return ui.labelNoComparison;
+}
+
+export function renderComparison(input: {
+  root: HTMLElement;
+  first: LoanScenarioResult;
+  second: LoanScenarioResult;
+  comparison: ComparisonResult;
+  context: ViewContext;
+}): void {
+  const { root, first, second, comparison, context } = input;
+  const { ui } = context;
+  root.innerHTML = `<div class="loan-apr-result-intro"><div><h2>${escapeText(ui.labelWinner)}</h2></div><p>${escapeText(winnerText(first, second, comparison, ui))}<br><span>${escapeText(getDifferenceLabel(comparison))}</span></p></div>${visualComparison(first, second, comparison, ui)}<div class="loan-apr-result-panels">${scenarioPanel({ result: first, other: second, side: "a", comparison, context })}${scenarioPanel({ result: second, other: first, side: "b", comparison, context })}</div><div class="loan-apr-method"><span>${escapeText(ui.labelFormula)}</span><p>${escapeText(ui.labelFormulaText)}</p><small>${escapeText(ui.labelApproximation)}</small></div>`;
+}
+
+function copyWinner(
+  first: LoanScenarioResult,
+  second: LoanScenarioResult,
+  comparison: ComparisonResult,
+  ui: LoanAprScenarioCalculatorUI,
+): string {
+  if (comparison.winner === "a") return first.name;
+  if (comparison.winner === "b") return second.name;
+  if (comparison.winner === "tie") return ui.labelTie;
+  return ui.labelNoComparison;
+}
+
+function copyLine(result: LoanScenarioResult, context: ViewContext): string {
+  if (!result.valid)
+    return `${result.name}: ${context.ui.labelNeedValidInputs}`;
+  return `${result.name}: ${percent(result.effectiveApr)} effective APR, ${money(result.monthlyPayment, context.locale, context.currency)} monthly payment, ${money(result.totalPaid, context.locale, context.currency)} total paid`;
+}
+
+export function formatResultForCopy(input: {
+  first: LoanScenarioResult;
+  second: LoanScenarioResult;
+  comparison: ComparisonResult;
+  context: ViewContext;
+}): string {
+  const { first, second, comparison, context } = input;
+  return `${context.ui.labelWinner}: ${copyWinner(first, second, comparison, context.ui)}\n${copyLine(first, context)}\n${copyLine(second, context)}`;
+}

package/src/tool/loanAprScenarioCalculator/entry.ts

@@ -0,0 +1,28 @@
+import type { FinanceToolEntry, ToolLocaleContent } from "../../types";
+import type { LoanAprScenarioCalculatorUI } from "./ui";
+
+export type LoanAprScenarioCalculatorLocaleContent =
+  ToolLocaleContent<LoanAprScenarioCalculatorUI>;
+
+export const loanAprScenarioCalculator: FinanceToolEntry<LoanAprScenarioCalculatorUI> =
+  {
+    id: "loan-apr-scenario-calculator",
+    icons: { bg: "mdi:cash-multiple", fg: "mdi:scale-balance" },
+    i18n: {
+      de: () => import("./i18n/de").then((module) => module.content),
+      en: () => import("./i18n/en").then((module) => module.content),
+      es: () => import("./i18n/es").then((module) => module.content),
+      fr: () => import("./i18n/fr").then((module) => module.content),
+      id: () => import("./i18n/id").then((module) => module.content),
+      it: () => import("./i18n/it").then((module) => module.content),
+      ja: () => import("./i18n/ja").then((module) => module.content),
+      ko: () => import("./i18n/ko").then((module) => module.content),
+      nl: () => import("./i18n/nl").then((module) => module.content),
+      pl: () => import("./i18n/pl").then((module) => module.content),
+      pt: () => import("./i18n/pt").then((module) => module.content),
+      ru: () => import("./i18n/ru").then((module) => module.content),
+      sv: () => import("./i18n/sv").then((module) => module.content),
+      tr: () => import("./i18n/tr").then((module) => module.content),
+      zh: () => import("./i18n/zh").then((module) => module.content),
+    },
+  };

package/src/tool/loanAprScenarioCalculator/evaluator.ts

@@ -0,0 +1,21 @@
+import type { ComparisonResult, LoanScenarioResult } from "./logic";
+
+export type ScenarioBadge = "lower" | "higher" | "neutral" | "invalid";
+
+export function getScenarioBadge(
+  side: "a" | "b",
+  result: LoanScenarioResult,
+  comparison: ComparisonResult,
+): ScenarioBadge {
+  if (!result.valid || comparison.message === "invalid") return "invalid";
+  if (comparison.winner === "tie") return "neutral";
+  return comparison.winner === side ? "lower" : "higher";
+}
+
+export function getDifferenceLabel(comparison: ComparisonResult): string {
+  if (comparison.message === "invalid")
+    return "Enter valid values to compare both offers.";
+  if (comparison.message === "tie")
+    return "The two scenarios produce nearly the same effective annual cost.";
+  return `${comparison.difference.toFixed(2)} percentage points separate the effective annual costs.`;
+}

package/src/tool/loanAprScenarioCalculator/i18n/de.ts

@@ -0,0 +1,194 @@
+import type { ToolLocaleContent } from "../../../types";
+import { bibliography } from "../bibliography";
+import type { LoanAprScenarioCalculatorUI } from "../ui";
+
+const ui: LoanAprScenarioCalculatorUI = {
+  labelScenarioA: "Angebot A",
+  labelScenarioB: "Angebot B",
+  labelScenarioName: "Name des Angebots",
+  labelCurrency: "Währung",
+  labelApproximateRates:
+    "Näherungswerte für die Planung, keine Live-Wechselkurse.",
+  labelPrincipal: "Geliehener Betrag",
+  labelTerm: "Laufzeit",
+  labelMonths: "Monate",
+  labelInputBasis: "Welche Angabe kennen Sie?",
+  labelAnnualRate: "Nominaler Jahreszins",
+  labelMonthlyPayment: "Bekannte Monatsrate",
+  labelUpfrontFees: "Anfangsgebühren",
+  labelMonthlyFees: "Monatliche Gebühren",
+  labelFinalFees: "Schlussgebühr",
+  labelOfferNameA: "Angebot A",
+  labelOfferNameB: "Angebot B",
+  labelRateMode: "Ich kenne den Zinssatz",
+  labelPaymentMode: "Ich kenne die Monatsrate",
+  labelPreset: "Vergleich starten",
+  labelPresetBalanced: "Ausgewogene Angebote",
+  labelPresetLowFee: "Niedriger Zins mit Gebühren",
+  labelPresetLongTerm: "Längere Laufzeit",
+  labelReset: "Werte zurücksetzen",
+  labelCopy: "Vergleich kopieren",
+  labelCopied: "Vergleich kopiert",
+  labelEffectiveApr: "Effektive jährliche Kosten",
+  labelNominalRate: "Nominalzins",
+  labelMonthlyPaymentResult: "Monatsrate",
+  labelTotalPaid: "Gesamtzahlung",
+  labelTotalFees: "Gebühren im Szenario",
+  labelFinanceCost: "Kosten über dem Darlehen",
+  labelNetCashReceived: "Auszahlung nach Anfangsgebühren",
+  labelWinner: "Welches Angebot kostet weniger?",
+  labelLowerCost: "Geringere effektive Kosten",
+  labelHigherCost: "Höhere effektive Kosten",
+  labelTie: "Fast gleich",
+  labelNeedValidInputs: "Gültige Angaben erforderlich",
+  labelInvalidPrincipal:
+    "Der geliehene Betrag muss größer als null und höher als die Anfangsgebühren sein.",
+  labelInvalidTerm: "Verwenden Sie eine ganze Laufzeit von 1 bis 600 Monaten.",
+  labelInvalidFees: "Gebühren dürfen nicht negativ sein.",
+  labelInvalidPayment:
+    "Geben Sie eine positive Monatsrate ein, die die Auszahlung zurückzahlt.",
+  labelInvalidRate:
+    "Verwenden Sie einen nominalen Jahreszins von 0 % bis 100 %.",
+  labelNoComparison: "Vervollständigen Sie beide Angebote für den Vergleich.",
+  labelTimeline: "Zahlungsverlauf",
+  labelStart: "Start",
+  labelMonthly: "Monatlich",
+  labelEnd: "Letzter Monat",
+  labelFormula: "So funktioniert der Vergleich",
+  labelFormulaText:
+    "Die effektiven jährlichen Kosten sind der annualisierte Monatszins, bei dem Auszahlung und abgezinste Raten samt Gebühren übereinstimmen.",
+  labelApproximation:
+    "Die Schätzung setzt gleiche Monatsraten, keine tilgungsfreie Zeit und nur die eingegebenen Gebühren voraus. Sie ersetzt nicht die Angaben des Kreditgebers.",
+  labelScenarioSummary: "Szenarioübersicht",
+  currencyCode: "EUR",
+  currencyLocale: "de-DE",
+};
+
+const faq = [
+  {
+    question:
+      "Was ist der Unterschied zwischen Zinssatz und effektiven jährlichen Kosten?",
+    answer:
+      "Der nominale Zinssatz beschreibt die Zinsen auf den Saldo. Die effektiven jährlichen Kosten berücksichtigen zusätzlich Zeitpunkt und Höhe der eingegebenen Anfangs-, Monats- und Schlussgebühren.",
+  },
+  {
+    question: "Kann ich statt eines Zinssatzes eine Monatsrate eingeben?",
+    answer:
+      "Ja. Wählen Sie für das Angebot die bekannte Monatsrate. Der Rechner ermittelt den Monatszins, der Auszahlung, Zahlungsstrom und Gebühren dieses Szenarios entspricht.",
+  },
+  {
+    question: "Welches Angebot ist günstiger?",
+    answer:
+      "Vergleichen Sie zuerst die effektiven jährlichen Kosten und prüfen Sie danach Gesamtzahlung und Auszahlung. Bei unterschiedlicher Laufzeit oder Kredithöhe sollte die Entscheidung alle drei Signale berücksichtigen.",
+  },
+  {
+    question: "Sind das die offiziellen Kreditkosten des Anbieters?",
+    answer:
+      "Nein. Es ist eine transparente Szenarioschätzung anhand Ihrer Eingaben. Kreditgeber und Länder können Kosten, Zahlungstermine, Steuern und Versicherungen anders berücksichtigen.",
+  },
+];
+
+const howTo = [
+  {
+    name: "Betrag und Laufzeit eingeben",
+    text: "Geben Sie für jedes Angebot den ausgezahlten Betrag und die Zahl der Monatsraten ein.",
+  },
+  {
+    name: "Bekannte Angabe auswählen",
+    text: "Geben Sie je nach Angebot den nominalen Jahreszins oder die bekannte Monatsrate ein.",
+  },
+  {
+    name: "Gebühren ergänzen",
+    text: "Tragen Sie Gebühren zu Beginn, pro Monat und am Ende ein, damit der Zahlungsstrom vollständig ist.",
+  },
+  {
+    name: "Vergleich lesen",
+    text: "Nutzen Sie die effektiven jährlichen Kosten und prüfen Sie anschließend Gesamtzahlung und Auszahlung.",
+  },
+];
+
+const schemas = [
+  {
+    "@context": "https://schema.org",
+    "@type": "SoftwareApplication",
+    name: "Kredit APR Szenario Rechner",
+    description:
+      "Vergleicht zwei Kreditszenarien mit Zinsen, Raten und Gebühren.",
+    applicationCategory: "FinanceApplication",
+    operatingSystem: "All",
+    offers: { "@type": "Offer", price: "0", priceCurrency: "EUR" },
+  },
+  {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: faq.map((item) => ({
+      "@type": "Question",
+      name: item.question,
+      acceptedAnswer: { "@type": "Answer", text: item.answer },
+    })),
+  },
+  {
+    "@context": "https://schema.org",
+    "@type": "HowTo",
+    name: "Zwei Kreditangebote vergleichen",
+    description: "Vergleicht Zahlungsströme und effektive jährliche Kosten.",
+    step: howTo.map((step, index) => ({
+      "@type": "HowToStep",
+      position: index + 1,
+      name: step.name,
+      text: step.text,
+    })),
+  },
+];
+
+export const content: ToolLocaleContent<LoanAprScenarioCalculatorUI> = {
+  slug: "kredit-apr-szenario-rechner",
+  title: "Kredit APR Szenario Rechner",
+  description:
+    "Vergleichen Sie zwei Kreditangebote mit Zinsen, Zahlungsplan und Gebühren und schätzen Sie die effektiven jährlichen Kosten.",
+  ui,
+  faq,
+  bibliography,
+  howTo,
+  schemas,
+  seo: [
+    {
+      type: "title",
+      text: "Kreditangebote nach effektiven Kosten vergleichen",
+      level: 2,
+    },
+    {
+      type: "paragraph",
+      html: "<p>Ein niedriger Werbezins kann eine Bearbeitungsgebühr, eine monatliche Servicegebühr oder eine Schlusszahlung verbergen. Dieser Rechner macht daraus zwei vergleichbare Zahlungsströme und zeigt die Kosten des tatsächlich ausgezahlten Geldes.</p>",
+    },
+    { type: "title", text: "Was die Schätzung enthält", level: 3 },
+    {
+      type: "paragraph",
+      html: "<p>Geben Sie Betrag, Laufzeit, Zinssatz oder Monatsrate sowie Gebühren zu verschiedenen Zeitpunkten ein. Der Rechner findet den Monatszins, der Auszahlung und abgezinste Zahlungen samt Gebühren ausgleicht, und annualisiert ihn.</p>",
+    },
+    {
+      type: "paragraph",
+      html: "<p>Damit wird der Preis eines Kredits breiter betrachtet als nur der Nominalzins. Das Ergebnis bleibt eine Schätzung, weil offizielle Angaben je nach Land weitere Kosten und Annahmen enthalten können.</p>",
+    },
+    { type: "title", text: "Ergebnis richtig lesen", level: 3 },
+    {
+      type: "list",
+      items: [
+        "Vergleichen Sie die effektiven Kosten bei gleicher Kredithöhe und Laufzeit.",
+        "Prüfen Sie die Gesamtzahlung für die absolute Belastung.",
+        "Beachten Sie die Auszahlung nach Anfangsgebühren.",
+        "Nutzen Sie den Zahlungsverlauf, um den Zeitpunkt jeder Kostenart zu sehen.",
+      ],
+    },
+    {
+      type: "tip",
+      title: "Kreditunterlagen bleiben die Referenz",
+      html: "<p>Vergleichen Sie bei einem echten Vertrag die offiziellen Angaben des Kreditgebers mit denselben Annahmen. Fragen Sie nach Versicherungen, Steuern, variablen Zinsen und vorzeitigen Rückzahlungskosten.</p>",
+    },
+    { type: "title", text: "Grenzen der Szenarioschätzung", level: 3 },
+    {
+      type: "paragraph",
+      html: "<p>Das Tool setzt gleiche Monatsraten, keine tilgungsfreie Zeit und Gebühren zu Beginn, während der Laufzeit oder im letzten Monat voraus. Es bestätigt weder Leistbarkeit noch Genehmigung oder den offiziellen APR eines Produkts.</p>",
+    },
+  ],
+};

package/src/tool/loanAprScenarioCalculator/i18n/en.ts

@@ -0,0 +1,194 @@
+import type { ToolLocaleContent } from "../../../types";
+import { bibliography } from "../bibliography";
+import type { LoanAprScenarioCalculatorUI } from "../ui";
+
+const ui: LoanAprScenarioCalculatorUI = {
+  labelScenarioA: "Offer A",
+  labelScenarioB: "Offer B",
+  labelScenarioName: "Offer name",
+  labelCurrency: "Currency",
+  labelApproximateRates:
+    "Uses approximate planning factors, not live exchange rates.",
+  labelPrincipal: "Amount borrowed",
+  labelTerm: "Repayment term",
+  labelMonths: "months",
+  labelInputBasis: "What do you know?",
+  labelAnnualRate: "Nominal annual rate",
+  labelMonthlyPayment: "Known monthly payment",
+  labelUpfrontFees: "Upfront fees",
+  labelMonthlyFees: "Monthly fees",
+  labelFinalFees: "Final fee",
+  labelOfferNameA: "Offer A",
+  labelOfferNameB: "Offer B",
+  labelRateMode: "I know the rate",
+  labelPaymentMode: "I know the payment",
+  labelPreset: "Start with a comparison",
+  labelPresetBalanced: "Balanced offers",
+  labelPresetLowFee: "Low rate with fees",
+  labelPresetLongTerm: "Longer term",
+  labelReset: "Reset values",
+  labelCopy: "Copy comparison",
+  labelCopied: "Comparison copied",
+  labelEffectiveApr: "Effective annual cost",
+  labelNominalRate: "Nominal rate",
+  labelMonthlyPaymentResult: "Monthly payment",
+  labelTotalPaid: "Total paid",
+  labelTotalFees: "Fees in the scenario",
+  labelFinanceCost: "Cost above principal",
+  labelNetCashReceived: "Cash received after upfront fees",
+  labelWinner: "Which offer costs less?",
+  labelLowerCost: "Lower effective cost",
+  labelHigherCost: "Higher effective cost",
+  labelTie: "Nearly tied",
+  labelNeedValidInputs: "Needs valid inputs",
+  labelInvalidPrincipal:
+    "The amount borrowed must be greater than the upfront fees and above zero.",
+  labelInvalidTerm: "Use a whole repayment term from 1 to 600 months.",
+  labelInvalidFees: "Fees cannot be negative.",
+  labelInvalidPayment:
+    "Enter a positive monthly payment that can repay the net cash received.",
+  labelInvalidRate: "Use a nominal annual rate from 0% to 100%.",
+  labelNoComparison: "Complete both offers to compare them.",
+  labelTimeline: "Payment timeline",
+  labelStart: "Start",
+  labelMonthly: "Each month",
+  labelEnd: "Final month",
+  labelFormula: "How the comparison works",
+  labelFormulaText:
+    "The effective annual cost is the annualised monthly rate that makes the cash received equal to the discounted payments and fees.",
+  labelApproximation:
+    "Estimate assumes equal monthly payments, no grace period and only the fees you enter. It does not replace the APR or TAE in a lender disclosure.",
+  labelScenarioSummary: "Scenario summary",
+  currencyCode: "USD",
+  currencyLocale: "en-US",
+};
+
+const faq = [
+  {
+    question:
+      "What is the difference between the interest rate and the effective annual cost?",
+    answer:
+      "The nominal interest rate describes the interest charged on the balance. The effective annual cost in this calculator also reflects the timing and amount of the upfront, monthly and final fees you enter.",
+  },
+  {
+    question: "Can I enter a monthly payment instead of an interest rate?",
+    answer:
+      "Yes. Choose the known monthly payment option for that offer. The calculator infers the monthly rate that matches the amount received, the payment stream and the fees in the scenario.",
+  },
+  {
+    question: "Which offer is cheaper?",
+    answer:
+      "Compare the effective annual cost first, then review total paid and cash received. A lower percentage can still have a higher total cost when the term or amount differs, so the decision should use all three signals.",
+  },
+  {
+    question: "Is this the official APR or TAE from a lender?",
+    answer:
+      "No. It is a transparent scenario estimate based on your inputs. Lenders and jurisdictions may include or exclude costs differently and may use different payment dates, taxes, insurance or variable-rate assumptions.",
+  },
+];
+
+const howTo = [
+  {
+    name: "Enter the amount and term",
+    text: "Add the amount you would receive and the number of monthly repayments for each offer.",
+  },
+  {
+    name: "Choose the known offer detail",
+    text: "Enter either the nominal annual rate or the monthly payment, depending on what the offer gives you.",
+  },
+  {
+    name: "Add every relevant fee",
+    text: "Enter fees paid at the start, each month or at the end so the comparison reflects the cash flow you want to test.",
+  },
+  {
+    name: "Read the cost scanner",
+    text: "Use effective annual cost to compare pricing, then check total paid and net cash received before deciding which offer fits your question.",
+  },
+];
+
+const schemas = [
+  {
+    "@context": "https://schema.org",
+    "@type": "SoftwareApplication",
+    name: "Loan APR scenario calculator",
+    description:
+      "Compare two loan scenarios with rates, payments and fees using a transparent effective annual cost estimate.",
+    applicationCategory: "FinanceApplication",
+    operatingSystem: "All",
+    offers: { "@type": "Offer", price: "0", priceCurrency: "EUR" },
+  },
+  {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: faq.map((item) => ({
+      "@type": "Question",
+      name: item.question,
+      acceptedAnswer: { "@type": "Answer", text: item.answer },
+    })),
+  },
+  {
+    "@context": "https://schema.org",
+    "@type": "HowTo",
+    name: "Compare two loan offers with rates and fees",
+    description:
+      "Use the calculator to model two loan cash flows and compare their effective annual cost.",
+    step: howTo.map((step, index) => ({
+      "@type": "HowToStep",
+      position: index + 1,
+      name: step.name,
+      text: step.text,
+    })),
+  },
+];
+
+export const content: ToolLocaleContent<LoanAprScenarioCalculatorUI> = {
+  slug: "loan-apr-scenario-calculator",
+  title: "Loan APR scenario calculator",
+  description:
+    "Compare two loan offers with their interest, payment schedule and fees to estimate the effective annual cost before you decide.",
+  ui,
+  faq,
+  bibliography,
+  howTo,
+  schemas,
+  seo: [
+    {
+      type: "title",
+      text: "Compare loan offers by effective annual cost",
+      level: 2,
+    },
+    {
+      type: "paragraph",
+      html: "<p>A low advertised interest rate can hide an arrangement fee, a monthly service charge or a final cost. This loan APR scenario calculator turns the details you have into two comparable cash flow scenarios, so you can see the cost of the money you actually receive.</p>",
+    },
+    { type: "title", text: "What the estimate includes", level: 3 },
+    {
+      type: "paragraph",
+      html: "<p>For each offer, enter the amount borrowed, the repayment term, either the nominal annual rate or the known monthly payment, and the fees charged at different points in the loan. The calculator finds the monthly rate that balances the net cash received against the discounted payments and fees, then annualises it.</p>",
+    },
+    {
+      type: "paragraph",
+      html: "<p>This mirrors the useful comparison principle behind APR and TAE: the price of credit is broader than the interest rate alone. The result is deliberately labelled an estimate because official disclosures may follow jurisdiction-specific rules and include assumptions that are not present in your scenario.</p>",
+    },
+    { type: "title", text: "How to read the result", level: 3 },
+    {
+      type: "list",
+      items: [
+        "Compare effective annual cost when the amount and term are alike.",
+        "Check total paid to understand the absolute cash impact.",
+        "Check cash received after upfront fees so a fee is not mistaken for borrowed money.",
+        "Use the timeline to see when each cost enters the scenario.",
+      ],
+    },
+    {
+      type: "tip",
+      title: "Use the lender disclosure as the final reference",
+      html: "<p>If you are comparing a real contract, match the lender's APR or TAE against the same assumptions. Ask about insurance, taxes, variable rates, early repayment charges and any fee that is not represented by your inputs.</p>",
+    },
+    { type: "title", text: "Limits of a scenario estimate", level: 3 },
+    {
+      type: "paragraph",
+      html: "<p>This tool assumes equal monthly payments, no grace period and fees that you can place at the start, during the term or in the final month. It does not certify affordability, approval, legality or the official APR of a product. Use it to make a better comparison from the information you have, then verify the offer documents.</p>",
+    },
+  ],
+};