Skip to content

Wallos: Open-source, self-hostable personal subscription tracker. Visualize your recurring expenses, manage your budget, and save money.

23.8 KB
Raw Blame
<?php
/*
  A new account's categories and payment methods are in that account's language.

  Every path that creates an account carried its own copy of the same English
  list, so somebody who registered in German got an application that was German
  everywhere except in its own data - on the dashboard, which is the first
  screen they ever see. The lists are held as translation keys now and resolved
  once, at the moment the account is created.

  Two properties are worth guarding rather than glancing at:

    - the fallback. There are thirty language files and these keys cannot be
      translated into all of them at once, so a file without them has to answer
      with the English string and never with the key itself.

    - the first account. It is the one account whose rows exist before a
      language does: createdatabase.php seeds them while the database is being
      created, and migration 000020 hands them to user 1. Renaming them at
      registration is the only moment the language is known and the rows are
      still untouched.
*/

require_once WALLOS_ROOT . '/includes/default_names.php';

/**
 * The languages Wallos ships a translation file for.
 *
 * @return string[]
 */
function default_names_test_languages()
{
    $languages = [];

    foreach (glob(WALLOS_ROOT . '/includes/i18n/*.php') as $file) {
        $name = basename($file, '.php');

        if ($name !== 'languages' && $name !== 'getlang') {
            $languages[] = $name;
        }
    }

    return $languages;
}

/**
 * The raw translation table of one language file, read without going through
 * the code under test.
 *
 * @param string $language
 * @return array<string, string>
 */
function default_names_test_table($language)
{
    $i18n = [];
    require WALLOS_ROOT . '/includes/i18n/' . $language . '.php';

    return $i18n;
}

/**
 * The names of one user's rows, in insertion order.
 *
 * @param SQLite3 $db
 * @param string  $table 'categories' or 'payment_methods'
 * @param int     $userId
 * @return string[]
 */
function default_names_test_rows($db, $table, $userId)
{
    $statement = $table === 'categories'
        ? $db->prepare('SELECT name FROM categories WHERE user_id = :userId ORDER BY id')
        : $db->prepare('SELECT name FROM payment_methods WHERE user_id = :userId ORDER BY id');

    $statement->bindValue(':userId', $userId, SQLITE3_INTEGER);
    $result = $statement->execute();

    $names = [];
    while ($result && $row = $result->fetchArray(SQLITE3_ASSOC)) {
        $names[] = $row['name'];
    }

    return $names;
}

wallos_test('the default categories are the account language, not English', function () {
    $english = default_categories('en');
    $german = default_categories('de');

    assert_same(17, count($english), 'English still has every default category');
    assert_same(17, count($german), 'German has every default category');

    assert_same('No category', $english[0], 'the first category is the placeholder');
    assert_same('Keine Kategorie', $german[0], 'and it is translated too');
    assert_same('Entertainment', $english[1], 'English second category');
    assert_same('Unterhaltung', $german[1], 'German second category');
    assert_same('Essen & Trinken', $german[4], 'an ampersand name is translated whole');

    assert_true($german !== $english, 'the two languages are not the same list');
});

wallos_test('the default payment methods translate the generic ones and keep the brands', function () {
    $english = default_payment_methods('en');
    $german = default_payment_methods('de');

    assert_same(31, count($english), 'every default payment method is there');
    assert_same(31, count($german), 'in every language');

    assert_same('PayPal', $english[0]['name'], 'a brand in English');
    assert_same('PayPal', $german[0]['name'], 'is the same brand in German');
    assert_same('Credit Card', $english[1]['name'], 'a generic method in English');
    assert_same('Kreditkarte', $german[1]['name'], 'is translated in German');
    assert_same('Bargeld', $german[4]['name'], 'and so is the last generic one');

    foreach ($english as $index => $method) {
        assert_same($method['icon'], $german[$index]['icon'],
            'the icon of ' . $method['name'] . ' does not depend on the language');
        assert_true(strpos($method['icon'], 'images/uploads/icons/') === 0,
            $method['name'] . ' keeps the icon path the rows are stored with');
    }
});

wallos_test('a language that has not translated a name yet answers in English', function () {
    // The property that makes this shippable without inventing translations:
    // every language file that does not carry a key answers with the English
    // string, and never with the key itself. Checked against the raw language
    // file rather than against a fixed expectation, so it keeps holding as
    // translations arrive.
    $english = default_categories('en');
    $englishMethods = default_payment_methods('en');
    $languages = default_names_test_languages();

    foreach ($languages as $language) {
        $table = default_names_test_table($language);
        $categories = default_categories($language);
        $methods = default_payment_methods($language);

        assert_same(17, count($categories), $language . ' has every default category');

        foreach (DEFAULT_CATEGORY_KEYS as $index => $key) {
            $expected = isset($table[$key]) ? $table[$key] : $english[$index];

            assert_same($expected, $categories[$index],
                $language . '/' . $key . ' is its own translation or the English one');
            assert_true(!in_array($categories[$index], DEFAULT_CATEGORY_KEYS, true),
                $language . '/' . $key . ' resolved to a name rather than to the key');
        }

        foreach (DEFAULT_PAYMENT_METHODS as $index => $method) {
            if (!isset($method['key'])) {
                assert_same($method['name'], $methods[$index]['name'],
                    $language . ' leaves the brand ' . $method['name'] . ' alone');

                continue;
            }

            $expected = isset($table[$method['key']])
                ? $table[$method['key']]
                : $englishMethods[$index]['name'];

            assert_same($expected, $methods[$index]['name'],
                $language . '/' . $method['key'] . ' is its own translation or the English one');
        }
    }

    assert_true(count($languages) >= 29,
        'every shipped language was checked (' . count($languages) . ')');
});

wallos_test('a language value that names no translation is English, not an error', function () {
    $english = default_categories('en');

    // The value arrives from a form field, an OIDC claim or the user table and
    // it decides a file name, so a path must never come out the other end.
    foreach (['', ' ', 'xx', 'not a language', '../i18n/en', 'en.php', '../../../etc/passwd', null] as $value) {
        assert_same($english, default_categories($value),
            var_export($value, true) . ' falls back to English');
    }
});

wallos_test('a language written as a BCP-47 tag finds its file', function () {
    // What a browser and an identity provider send. The file names use an
    // underscore, and a language nobody can reach is a language nobody gets.
    // "username" is a string the two Portuguese translations spell differently,
    // so it says which file was loaded.
    assert_same(default_names_test_table('pt_br')['username'],
        default_names_translations('pt-BR')['username'], 'pt-BR is the pt_br file');
    assert_same(default_names_test_table('pt')['username'],
        default_names_translations('pt')['username'], 'and pt is still pt');
    assert_true(default_names_test_table('pt')['username'] !== default_names_test_table('pt_br')['username'],
        'the two spellings really are different, so the check above can fail');
});

wallos_test('the seeding paths no longer carry an English list of their own', function () {
    // Three copies of the same list is how the English one survived being
    // fixed twice before. The names live in one file now.
    foreach (['registration.php', 'endpoints/admin/adduser.php', 'includes/oidc/oidc_create_user.php'] as $file) {
        $source = file_get_contents(WALLOS_ROOT . '/' . $file);

        assert_contains('default_categories($language)', $source,
            $file . ' seeds the categories in the account language');
        assert_contains('default_payment_methods($language)', $source,
            $file . ' seeds the payment methods in the account language');
        assert_not_contains("'Food & Beverages'", $source,
            $file . ' has no English category list left');
        assert_not_contains("'Charity & Donations'", $source,
            $file . ' has no English category list left');
        assert_not_contains("'Direct Debit'", $source,
            $file . ' has no English payment method list left');
    }

    // The first account is the one the loop above cannot describe: it is not
    // seeded at all, it is renamed.
    assert_contains('localize_default_names($db, $userId, $language)',
        file_get_contents(WALLOS_ROOT . '/registration.php'),
        'registration.php localizes the rows the first account inherits');
});

wallos_test('the first account is renamed into its language, rows and all', function () {
    // createdatabase.php seeded these rows and migration 000020 gave them to
    // user 1; the test database is built by running both, so this is the real
    // state a first registration finds.
    $db = wallos_test_open_database();
    wallos_test_create_user($db, 1, 'alice');

    $before = default_names_test_rows($db, 'categories', 1);
    assert_same(17, count($before), 'the installation seeded its categories');
    assert_same('No category', $before[0], 'in English');
    assert_same('Entertainment', $before[1], 'in English');

    $renamed = localize_default_names($db, 1, 'de');

    $after = default_names_test_rows($db, 'categories', 1);
    assert_same(default_categories('de'), $after, 'every category now reads in German');

    $methods = default_names_test_rows($db, 'payment_methods', 1);
    assert_same('PayPal', $methods[0], 'the brand is untouched');
    assert_same('Kreditkarte', $methods[1], 'the generic method is German');
    assert_same('Überweisung', $methods[2], 'and so is the next one');

    // 16 categories - "Software" is the same word in both languages, so that
    // row is not written at all - and the 4 generic payment methods.
    assert_same(20, $renamed, 'it reports what it renamed');

    $db->close();
});

wallos_test('renaming leaves English accounts and other people\'s rows alone', function () {
    $db = wallos_test_open_database();
    wallos_test_create_user($db, 1, 'alice');

    assert_same(0, localize_default_names($db, 1, 'en'),
        'an English account has nothing to rename');
    assert_same('Entertainment', default_names_test_rows($db, 'categories', 1)[1],
        'and its rows are untouched');

    // A second account's rows are its own, whatever language the first picks.
    wallos_test_create_user($db, 2, 'bob');
    $statement = $db->prepare('INSERT INTO categories (name, "order", user_id) VALUES (:name, 1, 2)');
    $statement->bindValue(':name', 'Entertainment', SQLITE3_TEXT);
    $statement->execute();

    localize_default_names($db, 1, 'de');

    assert_same(['Entertainment'], default_names_test_rows($db, 'categories', 2),
        "the other account's row is not renamed");

    $db->close();
});

wallos_test('a name somebody chose themselves is never rewritten', function () {
    $db = wallos_test_open_database();
    wallos_test_create_user($db, 1, 'alice');

    $statement = $db->prepare("UPDATE categories SET name = 'Filme' WHERE user_id = 1 AND name = 'Entertainment'");
    $statement->execute();

    localize_default_names($db, 1, 'de');

    $names = default_names_test_rows($db, 'categories', 1);
    assert_same('Filme', $names[1], 'a renamed row keeps the name it was given');
    assert_same('Musik', $names[2], 'while the untouched rows next to it are localized');

    $db->close();
});

wallos_test('every key the seeding uses exists in English', function () {
    // A typo in a key is invisible at runtime: it falls back to English, and
    // the English table does not have it either, so the account is seeded with
    // the key as its category name.
    $english = default_names_test_table('en');

    foreach (DEFAULT_CATEGORY_KEYS as $key) {
        assert_true(isset($english[$key]) && $english[$key] !== '',
            $key . ' has an English string');
    }

    foreach (DEFAULT_PAYMENT_METHODS as $method) {
        if (isset($method['key'])) {
            assert_true(isset($english[$method['key']]) && $english[$method['key']] !== '',
                $method['key'] . ' has an English string');
        }
    }
});

/*
  A category still carrying its untouched default name is what a display site
  recognises as "the no-category placeholder" - there is no other way to tell:
  categories.id is one global sequence shared by every account, not one per
  user, so only the very first row this application ever created is actually
  id 1, and nothing here can tell the placeholder apart from an ordinary
  category by id.

  Before this file existed, that comparison was against the literal English
  string "No category", which is exactly right when every account is seeded in
  English. Once an account can be seeded in German, comparing the same literal
  string stops recognising a German account's own untouched placeholder as the
  placeholder at all - default_no_category_name() is what a display site
  compares against instead: that account's own creation-language default,
  rather than an English literal.
*/

wallos_test('the no-category default matches what a fresh account of that language is actually seeded with', function () {
    // The property this function exists for: comparing $category['name'] to
    // default_no_category_name($account's own language) is exactly comparing
    // against what default_categories() put there in the first place.
    foreach (['en', 'de', 'fr', 'ja'] as $language) {
        assert_same(default_categories($language)[0], default_no_category_name($language),
            $language . " matches that language's own seeded placeholder name");
    }
});

wallos_test('the no-category default already differs by language, with no new translations needed', function () {
    // "no_category" is not a key #1216 introduced - it already existed,
    // already translated, in every language file, which is what makes this
    // safe to use for every account regardless of when it registered.
    assert_same('No category', default_no_category_name('en'), 'the English default');
    assert_same('Keine Kategorie', default_no_category_name('de'), 'the German default');
    assert_same('Pas de catégorie', default_no_category_name('fr'), 'the French default');
    assert_same('カテゴリなし', default_no_category_name('ja'), 'the Japanese default');
});

wallos_test('an unrecognised language answers the English default, same as everything else here', function () {
    foreach (['', 'xx', 'not a language', "../../../etc/passwd\0"] as $value) {
        assert_same('No category', default_no_category_name($value),
            var_export($value, true) . ' falls back to English');
    }
});

wallos_test('a category renamed by its owner matches neither default, and is shown as stored', function () {
    // The comparison this function feeds is an == against a fixed string:
    // a category somebody has genuinely renamed - to anything, including
    // another language's word for "no category" - is not the placeholder and
    // must not be relabelled out from under them.
    assert_true('Sin categoría' !== default_no_category_name('en'), 'not the English default');
    assert_true('Sin categoría' !== default_no_category_name('de'), 'nor the German one');
});

wallos_test('every display site recognises the placeholder by language, not by an English literal', function () {
    // The three places that used to compare $category['name'] == "No category":
    // stats.php's filter menu, includes/filters_menu.php, and the stats
    // subtitle in includes/stats_calculations.php. Each has to have moved to
    // default_no_category_name() and have stopped comparing to the fixed
    // English string, or a German account's own placeholder shows up as an
    // uncategorised-looking category named "Keine Kategorie" instead of being
    // recognised and re-translated to the page's own display language.
    foreach ([
        'stats.php',
        'includes/filters_menu.php',
        'includes/stats_calculations.php',
    ] as $path) {
        $source = file_get_contents(WALLOS_ROOT . '/' . $path);

        assert_contains('default_names.php', $source, $path . ' includes the default names helper');
        assert_contains('default_no_category_name(', $source,
            $path . ' compares against the account-language default');
        assert_true(strpos($source, '== "No category"') === false,
            $path . ' no longer compares against the English literal');
    }
});

wallos_test('an account that changes its language takes its default names with it', function () {
    $db = wallos_test_open_database();
    wallos_test_create_user($db, 1, 'alice');

    // A name of her own, to stay as it is.
    $statement = $db->prepare('UPDATE categories SET name = :name WHERE user_id = 1 AND name = :english');
    $statement->bindValue(':name', 'Kids', SQLITE3_TEXT);
    $statement->bindValue(':english', 'Gaming', SQLITE3_TEXT);
    $statement->execute();

    $renamed = localize_default_names_on_language_change($db, 1, 'en', 'de');

    assert_true($renamed > 0, 'the switch renames the seeded names');

    $categories = default_names_test_rows($db, 'categories', 1);
    assert_true(in_array('Unterhaltung', $categories, true), 'a seeded category now reads in German');
    assert_true(in_array('Kids', $categories, true), 'and the one she named herself is untouched');
    assert_true(!in_array('Entertainment', $categories, true), 'nothing seeded is left in English');

    $methods = default_names_test_rows($db, 'payment_methods', 1);
    assert_true(in_array('Kreditkarte', $methods, true), 'the generic payment methods follow too');
    assert_true(in_array('PayPal', $methods, true), 'and a brand stays a brand');

    $db->close();
});

wallos_test('a save that does not change the language renames nothing', function () {
    $db = wallos_test_open_database();
    wallos_test_create_user($db, 1, 'alice');

    assert_same(0, localize_default_names_on_language_change($db, 1, 'de', 'de'),
        'the same language twice is not a change');
    assert_same(0, localize_default_names_on_language_change($db, 1, 'en', ''),
        'and neither is a save that carries no language at all');

    assert_same('Entertainment', default_names_test_rows($db, 'categories', 1)[1],
        'so the rows are as they were');

    $db->close();
});

wallos_test('the endpoint that saves a language is the one that applies it', function () {
    $source = file_get_contents(WALLOS_ROOT . '/endpoints/user/save_user.php');

    assert_contains('localize_default_names_on_language_change($db, $userId, $storedLanguage, $language)', $source,
        'save_user.php applies the change through the guarded helper');
    assert_contains('SELECT main_currency, language FROM user WHERE id = :userId', $source,
        'and it reads the language it had, in the query it already ran');
});

wallos_test('switching from one non-English language to another renames the seeded names again', function () {
    $db = wallos_test_open_database();
    wallos_test_create_user($db, 1, 'alice');

    // She names one of the seeded rows herself, then walks English -> German -> French.
    $statement = $db->prepare('UPDATE categories SET name = :name WHERE user_id = 1 AND name = :english');
    $statement->bindValue(':name', 'Kids', SQLITE3_TEXT);
    $statement->bindValue(':english', 'Gaming', SQLITE3_TEXT);
    $statement->execute();

    localize_default_names_on_language_change($db, 1, 'en', 'de');
    $renamed = localize_default_names_on_language_change($db, 1, 'de', 'fr');

    assert_true($renamed > 0, 'the second switch renames what the first one wrote');

    $categories = default_names_test_rows($db, 'categories', 1);
    assert_true(in_array('Divertissement', $categories, true), 'a seeded category now reads in French');
    assert_true(!in_array('Unterhaltung', $categories, true), 'and none is left in German');
    assert_true(in_array('Kids', $categories, true), 'the name she chose is still hers');

    $methods = default_names_test_rows($db, 'payment_methods', 1);
    assert_true(in_array('Carte de crédit', $methods, true), 'the generic payment methods follow');
    assert_true(in_array('PayPal', $methods, true), 'and a brand stays a brand');

    $db->close();
});

wallos_test('switching back to English restores the English names', function () {
    $db = wallos_test_open_database();
    wallos_test_create_user($db, 1, 'alice');

    localize_default_names_on_language_change($db, 1, 'en', 'de');
    localize_default_names_on_language_change($db, 1, 'de', 'en');

    assert_same(default_categories('en'), default_names_test_rows($db, 'categories', 1),
        'every category reads in English again');
    assert_same('Credit Card', default_names_test_rows($db, 'payment_methods', 1)[1],
        'and so does the generic payment method');

    $db->close();
});

wallos_test('names that are still English are renamed even when the account was not in English', function () {
    $db = wallos_test_open_database();
    wallos_test_create_user($db, 1, 'alice');

    // The language on record says German, the rows were never localized: they
    // are the English ones the installation seeded. A switch to French still
    // finds them.
    $renamed = localize_default_names_on_language_change($db, 1, 'de', 'fr');

    assert_true($renamed > 0, 'the English names are found as well');
    assert_same(default_categories('fr'), default_names_test_rows($db, 'categories', 1),
        'every category reads in French');

    $db->close();
});

wallos_test('a language switch leaves another account\'s names alone', function () {
    $db = wallos_test_open_database();
    wallos_test_create_user($db, 1, 'alice');
    wallos_test_create_user($db, 2, 'bob');

    foreach (['Entertainment', 'Music'] as $name) {
        $statement = $db->prepare('INSERT INTO categories (name, "order", user_id) VALUES (:name, 1, 2)');
        $statement->bindValue(':name', $name, SQLITE3_TEXT);
        $statement->execute();
    }

    localize_default_names_on_language_change($db, 1, 'en', 'de');
    localize_default_names_on_language_change($db, 1, 'de', 'fr');

    assert_same(['Entertainment', 'Music'], default_names_test_rows($db, 'categories', 2),
        'the second account still has its own names');

    $db->close();
});

wallos_test('a rename never feeds the next one: each row is renamed once', function () {
    $db = wallos_test_open_database();
    wallos_test_create_user($db, 1, 'alice');

    // Rows carrying the German default for a position are all found before any
    // is written, so a target name that happens to be another position's
    // default is not renamed a second time.
    localize_default_names_on_language_change($db, 1, 'en', 'de');
    $renamed = localize_default_names($db, 1, 'fr', ['de']);

    $differs = fn($pair) => $pair[0] !== $pair[1];
    $categoriesThatDiffer = count(array_filter(array_map(null, default_categories('de'), default_categories('fr')), $differs));
    $methodsThatDiffer = count(array_filter(array_map(
        null,
        array_column(default_payment_methods('de'), 'name'),
        array_column(default_payment_methods('fr'), 'name')
    ), $differs));

    assert_same($categoriesThatDiffer + $methodsThatDiffer, $renamed,
        'one write for every default that differs between the two languages');
    assert_same(default_categories('fr'), default_names_test_rows($db, 'categories', 1),
        'and each category ends on its French name');

    $db->close();
});