1403861 - [API] Hide aggregate statistics about Suggested strings

Status: RESOLVED FIXED

(Webtools Graveyard :: Pontoon, enhancement)

Description

[Staś Małolepszy :stas]

To keep the API forward-compatible, let's rename approvedStrings and translatedStrings fields to something we better reflects their true meaning.  Here's one proposal:

    approvedStrings → approvedStrings (no change)
    translatedStrings → suggestedStrings
    translatedStrings = approved + suggested (new field)

Comment 1

[Matjaz Horvat [:mathjazz]]

Yes! Let's do this in the model, too.

I was planning to do it as part of https://bugzilla.mozilla.org/show_bug.cgi?id=1377969#c1, but I think separate bug is even better.

Comment 2

[Matjaz Horvat [:mathjazz]]

Given that bug 1377969 removes Suggested, I suggest :-) we make this a dependency.

Stas, could you clarify the last line of your proposal?

Comment 3

[[DEACTIVATED] Adrian Gaudebert]

I don't see the value of having that new `translatedStrings` field. The reason I see for us to do that would be if it's a very frequent use case and users want to avoid having to do that sum themselves. But given that we have no idea what our users will want out of the API, I would advise not to add that now. 

I agree that we need to make our "terminology" more coherent. That might require a broader discussion? Though I have the feeling that Matjaz already has this figured out somewhere. :)

Comment 4

[Staś Małolepszy :stas]

I guess I wanted to put the word "translated" somewhere in the proposal in comment 0. I agree that it's better not to add this new field now. We can always add it later if there's a use-case.

Are "strings" a Mozilla-specific lingo or are they universally understood? I wonder if the following renames would make more sense:

    totalStrings → totalTranslations
    approvedStrings → approvedTranslations
    translatedStrings → suggestedTranslations
    fuzzyStrings → fuzzyTranslations


Or even to make things very clear in the API:

    totalStrings → totalTranslationCount
    approvedStrings → approvedTranslationCount
    translatedStrings → suggestedTranslationCount
    fuzzyStrings → fuzzyTranslationCount

Comment 5

[Matjaz Horvat [:mathjazz]]

Matjaž does not have this figured out anywhere. :) But here are some of my thoughts.

We use the expression String since nobody has complained so far. :-) I've also seen:
- Unit (xliff)
- Message (fluent)
- Entry (gettext)

I'm not sure the term "Translation" is the best, especially for the "totalStrings → totalTranslations" case. It could lead to a confusion that totalTranslations only count translated strings, where in fact they also include strings with missing translations.

I agree about not adding the new translatedStrings field (approved + suggested), because we don't have a good use case for it. Since we'll be replacing the existing translatedStrings field with something like suggestions in bug 1377969, let's ignore translatedStrings altogether.

Note that we'll be also adding:
- word count in bug 1219431
- errors and warnings count in bug 1237667

How about this proposal:
- total_strings: no change
- translated_strings: no change
- fuzzy_strings: no change
- strings_with_errors: error_strings is weird
- strings_with_warnings: warning_strings is weird
- untranslated_strings (computed): currently missing_strings - strings are not missing, translations are
- strings_with_suggestions
==
- total_words: the number of words in all source strings
- translated_words: the number of words in translated source strings
- fuzzy_words: the number of words in fuzzy source strings
- words_with_errors: the number of words in source strings that have errors
- words_with_warnings: the number of words in source strings that have warnings
- untranslated_words (computed): the number of words in untranslated source strings
- words_with_suggestions

Comment 6

[Staś Małolepszy :stas]

In case of "strings_with_suggestions", do we plan to expose the number of strings for which there is at least one suggestion, or rather the number for suggestions across all strings?

Comment 7

[Matjaz Horvat [:mathjazz]]

(In reply to Staś Małolepszy :stas from comment #6)
> In case of "strings_with_suggestions", do we plan to expose the number of
> strings for which there is at least one suggestion, or rather the number for
> suggestions across all strings?

That's a good question.

For errors and warnings I was thinking about the former, because that way they compute with the rest of the statuses into 100% and we can visualize them on charts.

For suggestions, I was thinking about the latter, because they won't be visualized anyways. For some reason it also feels more natural to me to count the total number of suggestions. And, the number will be faster to compute with our existing data model.

Comment 8

[Staś Małolepszy :stas]

I'd like to move forward here with a minimal change first. I know there are plans to refactor the status fields at large but before that happens there's value in making the API a bit more sane.

I see two alternative proposal for renames without changing the way the data is collected (assuming I understand correctly how the current translatedStrings are computed):

    approvedStrings → approvedStrings (no change)
    translatedStrings → stringsWithSuggestions

or:

    approvedStrings → translatedStrings
    translatedStrings → stringsWithSuggestions

Matjaž, does this look right?

Comment 9

[Staś Małolepszy :stas]

(I'm using camelCase because it's the style recommended by GraphQL. In models.py we'll use snake_case.)

Comment 10

[Axel Hecht [:Pike]]

From the POV of an external client, I think using translatedStrings is a good thing, for people wanting to know if their stuff is localized. That's the term they'd use for "ready for me to use".

Comment 11

[Matjaz Horvat [:mathjazz]]

I like both of these ideas and I see the 2nd proposal as the step ahead of the 1st (a separate commit), so I prefer the 2nd.

I also like stringsWithSuggestions. It's not semantically correct for what it stands for ATM (Suggested in the UI), but it will be once we fix bug 1377969.

Comment 12

[[DEACTIVATED] Adrian Gaudebert]

Axel, your comment puzzles me. What would you call a string that has a suggestion, or a fuzzy translation, if you were to choose one word to describe all those 'non-approved' states? 

To me using "approved" is the one good way to say "this is ready to be used" as it means it went through the review process and was, well, approved. But, I'm no external client. :)

Comment 13

[Axel Hecht [:Pike]]

My take is that PMs in other parts of the org ask us for translations, and using that language in how we report data is good.

I'd hide any state that doesn't relate to "I can use that string" by default, as that's just an invitation to argue about a process.

Comment 14

[GitHub Bugzilla PR Linker]

Attachment: Link to GitHub pull-request: https://github.com/mozilla/pontoon/pull/736

Comment 15

[Staś Małolepszy :stas]

Comment on attachment 8920088 [details] [diff] [review]
Link to GitHub pull-request: https://github.com/mozilla/pontoon/pull/736

Until bug 1377969 is fixed, I suggest we simply hide the contentious fields.

Comment 16

[Staś Małolepszy :stas]

I think I would also prefer "approved" over "translated" because it speaks to the intent of the localizer. However, see my comment in bug 1377969 comment 11 for more thoughts about the naming. Are we trying to serve PMs or the localizers with these names?

Re. stringsWithSuggestions; would stringsWithUnreviewedSuggestions or stringsWithPendingSuggestions be a better name?

Comment 17

[Staś Małolepszy :stas]

I got a bit lost between bug 1377969 and this bug. They're very close to each other.  I'm pasting my comment from bug 1377969 comment 15 below.  It's a proposed naming scheme for the longer term once bug 1377969 is fixed and individual "WithPendingSuggestions" stats are implemented. In the names below I'm using "Pending Suggestions" instead of "Unreviewed". I find that the positve adjective makes the name more distinctive.

What if we went for the following naming scheme for string statistics:

    <VCS category> "Strings" ["WithPendingSuggestions"]

This would give us the following statistics:

    totalStrings
    totalStringsWithPendingSuggestions
    approvedStrings
    approvedStringsWithPendingSuggestions
    fuzzyStrings
    fuzzyStringsWithPendingSuggestions
    missingStrings
    missingStringsWithPendingSuggestions

and for suggestions across all kinds of strings:

    pendingSuggestions

Comment 18

[Matjaz Horvat [:mathjazz]]

Do we have a strong use case for storing the suggestions count for each status separately?

Note that calculating stats can be slow sometimes, which is why we denormalize them, and adding those fields likely means more DB queries when calculating them.

Comment 19

[Staś Małolepszy :stas]

That's a good point. Removing the suggestions for each status gives us the following fields. This is also the list as per https://github.com/mozilla/pontoon/pull/736:

    totalStrings
    approvedStrings
    fuzzyStrings
    missingStrings

Once bug 1377969 is fixed, we'll add the following two fields:

    totalStringsWithPendingSuggestions
    pendingSuggestions

I should perhaps rename this bug and file another one for adding these two fields.

Comment 20

[[github robot]]

Commit pushed to master at https://github.com/mozilla/pontoon

https://github.com/mozilla/pontoon/commit/6a8c517a3759e211e518bd4ad8a91c09244d62da
Bug 1403861 - Hide the Suggested statistic in the API (#736)

The Suggested status is pending a refactor in bug 1377969 and until it's
fixed, it's confusing to use `translatedStrings` for Suggested.

The Complete flag will now only be true if all strings are Approved.
Suggested and Fuzzy strings don't count towards this flag anymore.

Comment 21

[Staś Małolepszy :stas]

I filed bug 1410387 to re-expose the statistics about Suggested fields once bug 1377969  is fixed.