| Index: trunk/extensions/LiveTranslate/RELEASE-NOTES |
| — | — | @@ -5,7 +5,7 @@ |
| 6 | 6 | |
| 7 | 7 | |
| 8 | 8 | === Version 1.2 === |
| 9 | | -2011-08-xx |
| | 9 | +2011-08-14 |
| 10 | 10 | |
| 11 | 11 | * Rewrote translation control JavaScript to a jQuery plugin. |
| 12 | 12 | * Added caching layer utilizing memory and LocalStorage when available to speed up local translations. |
| Index: trunk/extensions/LiveTranslate/includes/jquery.liveTranslate.js |
| — | — | @@ -10,6 +10,11 @@ |
| 11 | 11 | |
| 12 | 12 | var _this = this; |
| 13 | 13 | |
| | 14 | + /** |
| | 15 | + * Start both the local and remote components of the translation process. |
| | 16 | + * |
| | 17 | + * @since 1.2 |
| | 18 | + */ |
| 14 | 19 | this.doTranslations = function() { |
| 15 | 20 | _this.runningJobs = 2; |
| 16 | 21 | |
| — | — | @@ -17,6 +22,15 @@ |
| 18 | 23 | _this.doRemoteTranslation( _this.completeTranslationProcess ); |
| 19 | 24 | }; |
| 20 | 25 | |
| | 26 | + /** |
| | 27 | + * Finds and returns the special words in the page by looking |
| | 28 | + * for spans with notranslate class. This obviously only works |
| | 29 | + * after these tags have been inserted with insertSpecialWords. |
| | 30 | + * |
| | 31 | + * @since 1.2 |
| | 32 | + * |
| | 33 | + * @return Array |
| | 34 | + */ |
| 21 | 35 | this.findSpecialWords = function() { |
| 22 | 36 | var words = []; |
| 23 | 37 | |
| — | — | @@ -26,7 +40,16 @@ |
| 27 | 41 | |
| 28 | 42 | return words; |
| 29 | 43 | }; |
| 30 | | - |
| | 44 | + |
| | 45 | + /** |
| | 46 | + * Does the local transltaions by obtaining the |
| | 47 | + * translations for the special words and replacing |
| | 48 | + * them where a translation is available. |
| | 49 | + * |
| | 50 | + * @since 1.2 |
| | 51 | + * |
| | 52 | + * @param {Function} callback |
| | 53 | + */ |
| 31 | 54 | this.doLocalTranslation = function( callback ) { |
| 32 | 55 | _this.memory.getTranslations( |
| 33 | 56 | { |
| — | — | @@ -49,13 +72,27 @@ |
| 50 | 73 | ); |
| 51 | 74 | }; |
| 52 | 75 | |
| | 76 | + /** |
| | 77 | + * Does the remote translation, ie everything not in notranslate spans. |
| | 78 | + * |
| | 79 | + * @since 1.2 |
| | 80 | + * |
| | 81 | + * @param {Function} callback |
| | 82 | + */ |
| 53 | 83 | this.doRemoteTranslation = function( callback ) { |
| 54 | 84 | var translator = new window.translationService(); |
| 55 | 85 | translator.done = callback; |
| 56 | 86 | lt.debug( 'Initiating remote translation' ); |
| 57 | 87 | translator.translateElement( $( '#bodyContent' ), _this.currentLang, _this.select.val() ); |
| 58 | 88 | }; |
| 59 | | - |
| | 89 | + |
| | 90 | + /** |
| | 91 | + * Function to be called once a transslation job has finished. |
| | 92 | + * Once there are no more running jobs, the state of the translation |
| | 93 | + * control is updated to translation completion. |
| | 94 | + * |
| | 95 | + * @since 1.2 |
| | 96 | + */ |
| 60 | 97 | this.completeTranslationProcess = function() { |
| 61 | 98 | if ( !--_this.runningJobs ) { |
| 62 | 99 | _this.translateButton.attr( "disabled", false ).text( lt.msg( 'livetranslate-button-translate' ) ); |
| — | — | @@ -67,6 +104,8 @@ |
| 68 | 105 | /** |
| 69 | 106 | * Inserts notranslate spans around the words specified in the passed array in the page content. |
| 70 | 107 | * |
| | 108 | + * @since 1.2 |
| | 109 | + * |
| 71 | 110 | * @param {Array} words |
| 72 | 111 | */ |
| 73 | 112 | this.insertSpecialWords = function( words ) { |
| — | — | @@ -82,6 +121,13 @@ |
| 83 | 122 | } |
| 84 | 123 | }; |
| 85 | 124 | |
| | 125 | + /** |
| | 126 | + * Obtain the special words and wrap occurances of them into notranslate spans. |
| | 127 | + * |
| | 128 | + * @since 1.2 |
| | 129 | + * |
| | 130 | + * @param {Function} callback |
| | 131 | + */ |
| 86 | 132 | this.obatinAndInsetSpecialWords = function( callback ) { |
| 87 | 133 | // TODO: only run at first translation |
| 88 | 134 | _this.memory.getSpecialWords( _this.currentLang, function( specialWords ) { |
| — | — | @@ -92,6 +138,12 @@ |
| 93 | 139 | } ); |
| 94 | 140 | }; |
| 95 | 141 | |
| | 142 | + /** |
| | 143 | + * Setup the translation control. |
| | 144 | + * Should be called on construction. |
| | 145 | + * |
| | 146 | + * @since 1.2 |
| | 147 | + */ |
| 96 | 148 | this.setup = function() { |
| 97 | 149 | var defaults = { |
| 98 | 150 | languages: {}, |
| — | — | @@ -123,6 +175,11 @@ |
| 124 | 176 | _this.bindEvents(); |
| 125 | 177 | }; |
| 126 | 178 | |
| | 179 | + /** |
| | 180 | + * Build up the HTML for the translation control and add it to the DOM element. |
| | 181 | + * |
| | 182 | + * @since 1.2 |
| | 183 | + */ |
| 127 | 184 | this.buildHtml = function() { |
| 128 | 185 | _this.attr( { |
| 129 | 186 | style: 'display:inline; float:right', |
| — | — | @@ -150,6 +207,11 @@ |
| 151 | 208 | _this.append( _this.select, _this.translateButton, _this.revertButton ); |
| 152 | 209 | }; |
| 153 | 210 | |
| | 211 | + /** |
| | 212 | + * Bind the event handlers to the components of the transltaion control. |
| | 213 | + * |
| | 214 | + * @since 1.2 |
| | 215 | + */ |
| 154 | 216 | this.bindEvents = function() { |
| 155 | 217 | _this.translateButton.click( function() { |
| 156 | 218 | _this.originalHtml = $( '#bodyContent' ).html(); |