However, I noticed that currently, it brings all translated items back, even if they are just translated instead of only being approved. This is because ResourceUtils needs an api version parameter in order to not bring translated items, however, at this point nothing (Optional.<String> absent()) is passed in the call.
I am willing to work on this and create a pull request to implement the change required, but not sure what would be the recommended approach.
Will go with the first approach, however, how the additional parameter should be called? apiVersion?
The FileResource.downloadTranslateFile end-point documented here
already has a path parameter fileType which is one of 'po', 'half_baked' or 'baked':
'po' means a gettext file - Fuzzy translations are marked as such in the PO format, but Translated and Approved are both included, and indistinguishable in this case.
'half_baked' includes Translated, Approved and Fuzzy.
'baked' includes Translated and Approved, but not Fuzzy.
The file type names are pretty silly, but if we extend the File end-point to distinguish between Translated and Approved, this (fileType) is the place to do it.
OTOH, if you're changing the TranslatedDocResource.getTranslationsWithDocId end-point, I think it would be best to add another query parameter. Let's say minContentState, which will be one of these:
http://zanata.org/zanata-platform/rest-api-docs/json_ContentState.html (but not New or Rejected)
Come to think of it, it would be better to use minContentState in FileResource too.
I would suggest we add minContentState as a query param there too. If you ask for fileType 'po' or the new fileType 'file', minContentState will be used to filter which messages are included. If you ask for fileType 'baked' or 'half-baked' as well as specifiying minContentState, an error will be returned.
I think I skimmed over what you said about ResourceUtils and its use of apiVersion.
That is some embarrassing old code! Unimportant analysis follows:
The methods org.zanata.rest.service.ResourceUtils#transferToTextFlowTarget (and org.zanata.rest.service.ResourceUtils#mapContentState) take an optional apiVersion.
If apiVersion is absent, Translated messages are treated the same as Approved for "backwards compatibility".
If apiVersion is present with any value, the translations' ContentStates are preserved. So apiVersion is being treated effectively as a boolean. I only found one concrete value for apiVersion, and it's "Editor", not a number (in org.zanata.rest.editor.service.TransUnitUtils#buildTargetTransUnit, as used by the React editor).
Besides the editor, the other two ways of reaching the function transferToTextFlowTarget come from org.zanata.service.impl.TranslationArchiveServiceImpl#buildTranslationFileArchive (which builds a zip file full of .po files) and org.zanata.rest.service.TranslatedDocResourceService#getTranslationsWithDocId (which implements the TranslatedDocResource REST end-point which I mentioned in the previous comment)
By the way, there's another place for the FileResource end-point which does similar things, in the method org.zanata.rest.service.FileService#downloadTranslationFile where it checks the ContentState before adding a message to the filteredTranslations (based on the baked/half-baked fileType). (On the other hand, if fileType=po, it delegates to org.zanata.rest.service.TranslatedDocResourceService#getTranslationsWithDocId from the previous paragraph)
So yeah, it's quite a mess.
I'm not sure which end-point you're using, perhaps both, but I still think it would be best to add a minContentState option (for now, it only needs to accept Translated or Approved).
If minContentState=Translated, org.zanata.rest.service.TranslatedDocResourceService#getTranslationsWithDocId will still pass apiVersion to org.zanata.rest.service.ResourceUtils#transferToTranslationsResource as absent, but if minContentState=Approved, apiVersion will be, let's say, "SupportsApproved".
I hope that makes some sense.
Except we didn't even update our own code.
Also 0.9 version of the Zanata plugin for Serge available at https://github.com/dragosv/serge-plugins (https://metacpan.org/release/Serge-Sync-Plugin-TranslationService-zanata). Need to write documentation and if possible wait until this pull request gets merged, so that I can have the full functionality for a 1.0 release.