Education - Specific prerequisites
The csi18n service, as far as I can tell, is entirely unique in using the concept of a Newmark, defined as an identifier to describe 'that which needs to be translated'. If the concept has another name elsewhere, I've yet to see it.
As a lay observer, it has seemed to me that automated and professional translations have hitherto been from a language, to another language. By abstracting out the need for a from language, using the newmark as a placeholder frees us from the need to have source material before starting work.
In usage, the newmark identifier can be any arbitrary Unicode string, but should be URL-encoded. If we know we need a "you're the winner" spiel at the end of a player vs player game, we can use the newmark "you're%20the%20winner" to refer to that text. We can then continue some other development without having yet committed to what that spiel is in English, much less any other language.
A Linked-List is a data structure containing a list of records, each of which can connect to another in sequence. While the Wikipedia entry suggests all linked-lists have a "next" field, it may be more useful here to consider their "next" pointer as the "previous" pointer, with the list growing to the left.
As a design consideration for csi18n, it is only the head of the linked-list which is normally of use: it represents the current version of the record. When it is itself superceded, a new head is created, and this new head has its "previous" pointer directed toward the previous head.
By using linked lists, records can be rolled back to any point in the past in the event of deletion or other undesired change.
Deletion. In a linked-list service, deletion doesn't remove the linked-list from the system. Rather, a new head - with a "deleted" field set to "true" - is created whereupon most of the service will ignore it. If required, the linked-list can then be updated again to undelete it.
CDMI Date and time
The service makes wide use of microseconds both in storing records and in higher level processing. This finds its way into headers and data in the form of CDMI dates and times. These are of the form "YYYY-MM-DDTHH.MM.SS.uuuuuuZ" where "T", "Z", "-" and "." are all literal characters, and "u" are microseconds. In use, the microseconds are always right-filled with zeros to be 6 digits long, so "412300Z" is legal, and "4123Z" is not.
The headers do accept HTTP dates and times and will convert them internally to CDMI forms. This may have consequences if you rely on such dates in HTTP conditionals:
If-Modified-Since, for example, will fail to work properly if there was an update within the same second to the record you're attempting to match. The service will accept
X-CDMI-If-Modified-Since as a header instead, but do note that there'll be unexpected behaviour from intermediate caches.
The data structures passed as content all use only CDMI.
The csi18n service relies on proper implementation of three other fields, and as such I'm equally interested in bug reports for:
- Security issues
- HTTP incompliance per RFC2616 (RFCs7230-7237 will be addressed later)
- RESTful incompliance
- csi18n issues
A bugzilla reporting system will be available; security issues should be emailed directly.
User Accounts: Superordinate v Subordinate
Csi18n makes use of two different kinds of user account.
The Superordinate account is standard for you if you develop for or manage a project using csi18n. The Subordinate account is for your end-users to use. The Superordinate is allowed to create Subordinate accounts at will, subject to service limits.
Example: you create a game utilising csi18n, and sell it to two people. Each of those people should be able to upload translations but we don't want them able to change the other's translation. Your game creates a Subordinate account for each of them: their differing credentials mean we can now protect them from each other; and your use of the Superordinate account means you can administer both of them.
Accounts created via the joining up page are all Superordinate accounts: such accounts may create translations visible only to themselves; they may also create subordinate accounts able to share translations visible only among each other, and who the Superordinate can be moderate.
"Private" translations can be made available to the wider public if the Superord toggles his "keyhole" flag.
Private translations are ordinarily accessible only to the Superordinate account and the Subordinate accounts he has created. While this is a great way to keep such material in-house, it may be desirable that they can be updated in-house and read-only from outside. This is accomplished by creating a keyhole through which other users can view translations (and prefer one over another), but are not able to contribute new material.
Keyholes are an all-or-nothing affair: when one is open, all "private" translations are made readable. That is, there's no support for allowing a keyhole to one private translation but not another.
All Superordinate users may open and close the keyhole to their private translations at any time, however see Limits to the service.
A visit link goes into your website, app, service etc and informs it that the content to go there is to be drawn from the csi18n service given the language preferences of your end-user. For example, you might have the visit link
https://rest.mpsvr.com:443/newmarks/197/A-winner-is-you in the section of your game that handles displaying who won the last game. When your end-user reaches that point, your software takes his language preference (known either from the localisation of the device, or his express preference) and makes an HTTP request with that preference in the header "Accept-Language: " to that link. The service replies with the appropriate content. (Serious coders should pre-cache specific responses, rather than wait until the very moment they're needed.)
A translation link, by contrast, always returns the same content whatever the end-users language preference: it links to a single translation in an already given language of a specified newmark. For example, the translation link
https://rest.mpsvr.com:443/xlates/32/book03-ch01-para23/en-AU/anonymous/419 will always return User 32's suggestion for what the Australian English translation would be of whatever "book03-ch01-para23" is. "anonymous" is here User 32's intent for who may access this record, and "419" indicates this is the 419th translation uploaded by any user, not just User 32.
Limits to the service
Limits may be lifted gratis for free projects, such as found in Open Source. Commercial projects however, will have to pay for them to be lifted. More details here.
- You can have as many SuperOrdinate accounts as you wish, however each may only moderate SubOrdinate accounts they created.
- By default each SuperOrdinate may create upto 16 SubOrdinates. Note that deleted SubOrdinates still count towards the limit.
- By default each SuperOrdinate may create upto 16 APIKeys.
- By default, accounts with keyholes open will have requests from the public through that keyhole limited to 128 per hour.